Journal à quand un code commenté ?

Posté par  .
Étiquettes : aucune
0
22
juin
2007
Salut la foule, c'est vendredi : c'est permis !

Je bosse dans le domaine du web : je crée des applications mais j'en intègre aussi. Lorsque je crée une application, je pense, en codant, au pauvre gus qui risque d'aller voir le code pour modifier l'appli. Pour que ce pauvre gus s'y retrouve, je place en en-tête quelques commentaires décrivant le "but" du script, si ce script dépend d'autres scripts (et lesquels) ainsi que la liste des fonctions/classes qu'il définit et la version minimale pour laquelle ce script est créé (pour php). Dans le code, à chaque action faite, à chaque ligne presque, je place un commentaire qui explique comment fonctionne la fonction, pourquoi je fais faire telle ou telle chose... ainsi, si quelqu'un va voir le code, il saura à quoi il sert...

Depuis quelques jours, j'intègre wordpress-mu à un environnement existant (ayant son propre mode d'authentification, par exemple) et pour se faire, je suis obligé de reprendre chaque étape de chaque action, de noter sur un papier la liste d'appels de fonctions, les noms de variables, la liste des dépendances... et c'est usant...
aucun commentaire dans le code sauf "// TODO : must translate this string" (super utile hein ?) ou "get_footer(); // get the footer" (tout aussi utile) ou encore (mon préféré) "// this is ugly !"

Mon coup de gueule : ok il ya une doc (très incomplète) ok la version MU est jeune mais quand même... ça serait quand même bien plus simple de commenter le code non ? C'est bien d'ouvrir un code et de vouloir que la communauté soit active dans le projet, mais, à mon sens, libérer du code ça passe aussi par donner les moyens aux autres de le modifier "simplement" sans qu'ils aient à chercher pendant des heures à quoi sert telle ou telle fonction apparemment cruciale...

Est-ce que j'en demande trop ?

  • # u r not alone

    Posté par  . Évalué à 10.

    Tu n'es pas le seul a avoir ce genre de problème... Rien ne m'agace plus que d'avoir, en entete d'un ficher, une tartine de /* */ qui explique la licence GPL en large et en travers, alors que rien n'explique le fonctionnement de la classe.

    >ça serait quand même bien plus simple de commenter le code non ?
    oui

    >Est-ce que j'en demande trop ?
    non.

    Je me demande si la différence entre les developpements perso et les dev professionnels n'est pas là...

    • [^] # Re: u r not alone

      Posté par  (site web personnel) . Évalué à 10.

      >Je me demande si la différence entre les developpements perso et les dev professionnels n'est pas là...

      Tu te trompes.

    • [^] # Re: u r not alone

      Posté par  . Évalué à 10.

      Les commentaires, ça doit être un réflexe.

      Et du coup, quelqu'un qui commente mal chez lui, commente également mal dans son boulot. En général.

      Parce que le commentaire, ça doit venir avant le code, ou à la rigueur en même temps. Si tu te dis : ça je le ferais plus tard, tu es déjà sur une pente glissante. Et surtout, tu multiplies le temps nécessaire, car quand tu reviens sur ton code 1 semaine ou 1 mois plus tard, c'est bien plus dur de le commenter.

      "Mais pourquoi j'ai écrit ça ?" "Bordel, ça correspond à quelle spec ?". Et j'en passe et des meilleures.

      Et c'est pas valable qu'en informatique...

      • [^] # Re: u r not alone

        Posté par  . Évalué à 10.

        Commenter du code ? Mais vous êtes fous. Après, si on voudra vous virer, on aura plus besoin de vous donc ca se fera sans problème.

        Alors, s'il vous plaît, gardez du travail pour les informaticiens, ne commentez pas vos codes !

        -- Qui aime bien, troll bien.

        • [^] # Re: u r not alone

          Posté par  . Évalué à 7.

          C'est d'ailleurs pour ça que j'ai toujours considéré que le Perl était un des meilleurs langages, puisque le code est auto commenté par lui même :)

          -- quitte à troller, autant aller jusqu'au bout.

          • [^] # Re: u r not alone

            Posté par  . Évalué à 3.

            Perl c'est surtout l'idéal pour pas se faire virer ! Et tu peux le commenter, ça n'en devient pas plus lisible pour autant ! Donc tu restes indispensable...

            -- le troll est mon ami. J'ai pas honte de mes amis.

    • [^] # Re: u r not alone

      Posté par  (Mastodon) . Évalué à 10.

      Mon code est toujours assez fortement commenté, que ce soit pour moi, ou pour le boulot.
      J'ai même tendance à mieux commenter encore quand c'est pour moi, parce que j'ai le temps, pas de deadline pourrie et de trucs à rendre vite fait mal fait pour avant-hier.


      Yth.

    • [^] # Re: u r not alone

      Posté par  . Évalué à 10.

      Je me demande si la différence entre les developpements perso et les dev professionnels n'est pas là...

      Heu non, pas trop. C'est quand meme étonnant de voir le nombre de gens qui pensent que les gens dans les entreprises codent proprement :)

      • [^] # Re: u r not alone

        Posté par  . Évalué à 6.

        je dirais meme qu'un certain nombre de code en entreprises sont 'sales' car les délais sont (trop) courts /o\.
        Impératifs qu'a beaucoup moins le logiciel libre.

        • [^] # Re: u r not alone

          Posté par  . Évalué à 5.

          C net.

          Je rajouterais, de plus, qu'ils sont certainement d'autant plus sales que ceux qui les écrivent savent pertinament bien que leur code ne sera jamais ou presque jamais relu/revu. (si ce n'est éventuellement par eux-mêmes et encore..).

          C'est triste, mais c'est comme ça.

        • [^] # Suivant le projet tu documentes ou pas,

          Posté par  . Évalué à 3.

          En même temps, ton patron ne te paye pas pour commenter ton code, même s'il te le reprochera.

          Généralement quand il s'aperçoit que tu commentes il te donne autre chose d'urgent, mais il te rappellera que tu ne commentes pas ton code le jour ou il en aura besoin.

          Sans compter, les projets qui commencent sans réelle cahier des charges mais qui doivent être fini pour hier.
          Et au moment ou tu leur montres ce qu'ils t'ont demandé, là tout est à refaire (y compris ta doc) car par le truchement de ton commercial qui est en contact avec LE cadre de la boite de vendeur de (Chausssures|Parfumerie|Pistolets|...) le projet ne répond plus à ce que pensais le cahier des charges qui était dans la tête de ce cadre mais qu'il ne t'as pas dit car sinon c'est pas assez sportif comme métier informaticien. Mais bon si ce cadre savait informatiquement parlant ce qu'il voulait tu n'aurait plus de métier.

          Dans l'exemple type, une fois, j'ai commencé par un simple ftp avec gestion des droits sur fichiers en http pour finir par un workflow complet entièrement recomposable.
          Sur ce genre de projet tu comprends que documenter complètement en codant peut te faire perdre du temps.

          D'ailleurs je vous signale, au passage, que le w3 essaye de mettre une norme pour les workflows des services webs après oasis et le workflow group.

          Bien sur je ne parle même pas des deadlines assassinent qui dynamiteront les élans lyriques.

  • # commenter le code?

    Posté par  . Évalué à 10.

    Je pense que commenter les fonctions implémentés est une bonne pratique à acquérir, si possible avec une description compatible avec doxygen et consorts...s'il y a un algorithme, expliquer celui-ci dans la description de la fonction etc...
    Par contre, commenter le code, je fait, pas! je donne toujours des noms très explicites à mes fonctions et variables pour pas avoir à le faire, surtout si j'ai déjà expliqué dans la description de la fonction le principe de son fonctionnement.
    Je trouve que commenter le code, ça reviens à dire qu'on a pondu du mauvais code, car pas compréhensible, donc qu'il faut corriger... En plus ça embrouille la lisibilité du code.
    Voilà ce que j'en pense...

    • [^] # Re: commenter le code?

      Posté par  . Évalué à 3.

      oui la compat avec dox est une idée sympa

      en ce qui concerne
      commenter le code, ça reviens à dire qu'on a pondu du mauvais code
      non ça revient à dire "je te donne un max d'infos pour pas que t'ai à te creuser la tête. Mais bien entendu si je mets un truc style
      "function affiche_heure() {
      echo time();
      }"
      vais pas commenter hein... je commente ce qui pourrait être obscur ou mal compris du premier coup...

      enfin
      En plus ça embrouille la lisibilité du code.
      ça on peut s'en arranger, on peut faire 2 versions : une commentée et l'autre pas ça permet d'avoir une sorte de doc si besoin, on peut aussi (lorsque c'est possible) faire des tabulations, perso je fais en sorte que les commentaires sortent de la limite des 80 caractères avec des tabs, ainsi les coms ne gênent pas le code...

      • [^] # Re: commenter le code?

        Posté par  . Évalué à 2.

        je commente ce qui pourrait être obscur ou mal compris du premier coup...


        Voilà dejà une difference sur ma façon de programmer et la tienne.
        Si j'estime qu'une partie du code pourrait être obscure ou mal comprise, je factorise et ajoute une nouvelle fonction implémentant cette partie avec un nom explicite et une description doxygen de la fonction... ça donne un code plus propre, plus lisible, plus conci, avec une description là ou elle doit être...
        c'est pas plus simple?

        • [^] # Re: commenter le code?

          Posté par  (site web personnel) . Évalué à 9.

          Y'a pas de mal à avoir du code commenté, mais ce que beaucoup de gens de comprennent pas, c'est qu'un commentaire est là pour dire pourquoi le code est ce qu'il est, et pas ce que le code fait.

          Et effectivement, le code avec un commentaire par ligne, soit c'est dans un tutorial, soit c'est une connerie ;-).

        • [^] # Re: commenter le code?

          Posté par  (site web personnel) . Évalué à 7.

          Si j'estime qu'une partie du code pourrait être obscure ou mal comprise, je factorise et ajoute une nouvelle fonction implémentant cette partie avec un nom explicite et une description doxygen de la fonction...


          Ca dépend du code en question. Sur un algo bien complexe, c'est pas en le factorisant que tu vas le rendre plus compréhensible, d'ailleurs, c'est souvent mission impossible de factoriser la chose en laissant un truc propre...

          J'ai bossé y'a pas très longtemps sur l'algo de placement intelligent de Kwin pour le porter sous Compiz, ce que j'ai pu remarquer:
          - Le début du code commence par un commentaire expliquant l'historique de l'algo, mais rien n'expliquant son fonctionnement...
          - Des commentaires dans le code qui après étude permettent de comprendre ce qu'il se passe.

          Donc, je pense que commenter une fonction et commenter son code sont deux choses qui s'entrecoupent. Si t'as l'un et pas l'autre, mais t'es un peu plus avancé mais pas trop.

          Bien, sur, cela ne sert à rien de commenter du code qui se lit de par lui meme ;)

          • [^] # Re: commenter le code?

            Posté par  (site web personnel) . Évalué à 2.

            Pour les algos un peu longs, moi, j'aime bien les commentaires du style

            /*
            1. faire ci
            2. faire ça
            3. encore un truc
            */

            Puis des /* 1. */, /* 2. */, ... qui se balladent dans le code après. Ceci-dit, faut faire gaffe à pas utiliser ça pour se rassurer, dans bien des cas, il aurait fallu découper ça en fonctions ...

            • [^] # Re: commenter le code?

              Posté par  . Évalué à 2.

              Parfaitement d'accord, j'ai codé un algo de réception DCF77 sans ce type de commentaire, quand j'ai du repasser voir comment il tournait, je n'ai rien compris (surtout que coder pour de l'AVR c'est beaucoup moins lisible que coder du C avec une libc standard).

              Bilan, tout réécrit (en bcp bcp mieux bien sûr), commenté, avec beaucoup de commentaires, et maintenant je comprend pourquoi je met telle valeur dans tel registre, etc...

        • [^] # Re: commenter le code?

          Posté par  . Évalué à 4.

          Non.

          Parfois, dans un souci d'optimisation de performances, il arrive de devoir développer des bouts de code pas propre ou obscur d'un point de vue algorithmique.

          • [^] # Re: commenter le code?

            Posté par  . Évalué à 4.

            parfois aussi, dans un souci de satisfaction de son ego, on essaye de faire le moins de lignes possibles même si ça en devient incompréhensible :)

    • [^] # Re: commenter le code?

      Posté par  . Évalué à 10.

      A mon sens, et je te rejoins, il ne faut jamais faire de commentaires pour explique ce que fait ton code. Si tu en arrives là, c'est que tu as pondu un monstre immaintenable. Par contre, je rajoute souvent des commentaires pour expliquer pourquoi mon code fait ceci ou cela, et cela prend généralement place dans l'entête de la fonction. Exemple "mauvais" : 
      fopen();
// début de la boucle
while (!eof()) {
  list.add(readln());
  // ligne suivante
  next();
} // while (!eof())
fclose();
      Tous ces commentaires sont totalement inutiles, et le lecteur n'en sait pas plus grâce à eux. Le seul qui soit un petit peu défendable, c'est le "// while ..." qui, pour ceux qui n'ont pas un IDE moderne, permet de se retrouver ; et encore, il faut surtout éviter un trop grand nombre d'imbrications. Un truc comme ça : 
      /**
 * Chargement du fichier dans une liste de chaînes pour
 * pouvoir ensuite appeler une méthode standard de tri
 */
fopen();
while(!eof()) {
  list.add(readln());
  next();
}
      Est bien plus utile. Le lecteur n'a pas besoin de parcourir tout le code pour savoir ce que ça fait, le commentaire apporte un vrai plus sur le code par une vision globale.

      • [^] # Re: commenter le code?

        Posté par  (site web personnel) . Évalué à 3.

        J'ajouterai en plus que le code du "mauvais" exemple est finalement plus difficile à lire car "haché" et par conséquent plus difficile à comprendre au premier coup d'oeil.

      • [^] # Re: commenter le code?

        Posté par  . Évalué à 2.

        Voila ce qui ce passe quand on veut bien commenté, on met moins d'attention dans le code et on crée des bug


        /**
        * Chargement du fichier dans une liste de chaînes pour
        * pouvoir ensuite appeler une méthode standard de tri
        */
        fopen();
        while(!eof()) {
        list.add(readln());
        next();
        }
        fclose();

        • [^] # Re: commenter le code?

          Posté par  . Évalué à 2.

          sauf que si il l'avait réellement écrit, je pense qu'il aurait fait :

          fopen();
          fclose();

          puis il aurait rempli :
          fopen();
          while(! eof()) {
          //blabla
          next();
          }
          fclose();

          et ensuite tu remplaces le //blabla par ce que tu veux faire de tes lignes. Donc, il n'aurait pas oublié le fclose :)

          (enfin, j'espère pour lui)

          On va dire que je suis assez adepte du code qui se documente par lui même (un minimum) : bien choisir ses variables, bien choisir où sauter des lignes, indenter correctement. Bien choisir ses règles de développement et s'y tenir.
          Et bien commenter ce qui n'est pas trivial, en essayant de se mettre à la place d'un autre.

          L'idéal est ce que j'ai eu l'occasion de faire dans un boulot précédent : j'avais écrit une application (en perl), et c'est une autre personne qui l'a relue. Ca m'a permis de voir où étaient vraiment les points "durs". Parce que quand on est plongé dans son code pendant 5 mois d'affilé, il devient "facile à lire" et compréhensible/trivial pour soi, mais ce n'est pas forcément le cas pour les autres.

      • [^] # Re: commenter le code?

        Posté par  . Évalué à 1.

        faut pas tout prends au pied de la lettre hein :)
        Dans le code, à chaque action faite, à chaque ligne presque, je place un commentaire qui explique comment fonctionne la fonction, pourquoi je fais faire telle ou telle chose...


        je disais ça pour un cas extrême qui nécessite cela (un algo pas évident à comprendre du premier coup, ou pour les appels de variables. exemples :

        en début de fichier :
        /*
        mon_script.php

        depends of : machin.php, toto.php maconf.conf

        Contents : general function about "trucmush"

        functions defined : funcDoingThat, funcDoingThis, funcDoingNothing

        */


        et/ou pour une fonction :

        /*

        funcDoingThat

        globalvars : $global1 (defined in maconf.conf)
        used funcs : usedFunc (defined in machin.php)

        actions ; Do that thing

        */


        et, bien entendu, mettre tout ça à jour si modifié

    • [^] # Re: commenter le code?

      Posté par  . Évalué à 4.

      Je te rejoins complètement. Le code doit se lire comme un bouquin et un livre dans lequel il faut sans cesse se référer à des notes de bas de page c'est lourd à lire. Ceux qui ont tenté de lire une version traduite de l'Art de la Guerre de Sun Zu savent de quoi je parle : C'est bourré de notes historiques, d'explications de termes intraduisibles ou de concepts inconnus. Le code sera relu des centaines de fois pas des personnes différentes. Il doit donc être compréhensible de loin par quelqu'un qui a le même background. Si on fait du traitement du signal par exemple, on peut supposer que le lecteur sait ce qu'est une transformée de Fourier. Pas la peine de mettre un pavé de texte expliquant l'algo.

      Je met en général peu d'explications dans le code. Lorsque je met des commentaires, c'est pour expliquer ce qui semble non naturel (workaround pour un problème connu, etc) ou que quelqu'un pourrait prendre pour un bug/oubli/boulette alors que c'est voulu. Ca ne dispense pas de faire de la doc en particulier sur l'architecture et les choix effectués mais la place de ce type d'info n'est pas dans le code. Quelqu'un qui cherche à comprendre l'architecture du logiciel ne devrait pas avoir à aller fouiller dans les fichiers pour avoir une vue d'ensemble et savoir dans quelle partie du code il doit intervenir.

  • # Ascii art en commentaire dans les sources

    Posté par  . Évalué à 2.

    au fait j'entend de plus en plus parler de doxygen qu'est qu'il a de plus ?


    sinon il y a boxes http://boxes.thomasjensen.com/ , qui permet de dessiner des boites de commentaires et de les enelver dans pas mal de language ..

    Pourquoi on ne joindrait pas l'utile a l'agréable en mettant de l'ascii art en forme de schéma dans les commentaires du codes ??

    (je parles pas de ces trucs du genre international offuscation code competition ) .

    • [^] # Re: Ascii art en commentaire dans les sources

      Posté par  . Évalué à 5.

      Si je dois utiliser boxes un jour, ce sera pour enlever les cadres, certainement pas pour en rajouter. Rien de pire que les cadres, c'est "le mal" (c). Un commentaire multiligne, tu le fait comme ça : 
      /*
 * Wonderful function which prepares coffee and buys sugar
 * Don't forget to connect it to emacs
 */
      Surtout pas comme ca : 
      /***********************************************************/
/* Wonderful function which prepares coffee and buys sugar */
/* Don't forget to connect it to emacs                     */
/***********************************************************/
      A part faire des fichiers plus gros, rendre l'édition plus chiante pour aligner les fins de lignes, et alourdir la lecture, ça apporte quoi ?

      • [^] # Re: Ascii art en commentaire dans les sources

        Posté par  . Évalué à 3.

        A part faire des fichiers plus gros, rendre l'édition plus chiante pour aligner les fins de lignes, et alourdir la lecture, ça apporte quoi ?

        Ca apporte aussi des commentaires qui ne correspondent plus à ce que fait la fonction, par ce que la dernière personne qui a modifié à eu la flemme de mettre à jour le commentaire.

        Sinon, ne surtout pas oublier non plus les commentaires qui repetent les noms de fonctions, les paramètres et autres infos inutiles. Exemple :



        /****************** function machin truc *************************/
        * This is the implementation of function machin truc, which */
        * does machin truc */
        * Name of the function: machin truc */
        * Number of Parameter(s) : 2 */
        * Last modified : 23/02/01 */
        * Parameter(s) : */
        * - n : an integer (int) */
        * - z : a character (char) */
        /*****************************************************************/
        function machin_truc(int n, char z)
        {
        /* Begining of function machin_truc */
        ...
        /* end of function machin_truc */
        }
        /*-----------------------------------------------------------------------*/

    • [^] # Re: Ascii art en commentaire dans les sources

      Posté par  . Évalué à 7.

      au fait j'entend de plus en plus parler de doxygen qu'est qu'il a de plus ?


      par rapport à quoi? boxes? ils n'ont pas le même but, l'un est un gadget, l'autre est un outils de génération de documentation de code.
      Un avantage, de doxygen, c'est qu'il comprend plusieurs syntaxes pour pouvoir s'adapter à plusieurs langages de programmation. ce qui en fait un outils unifié si jamais tu dois mixer plusieurs langages dans un projet...
      Ensuite plusieurs autres systèmes comprennent les tags de doxygen qui est devenu plus ou moins un standard, et qui lui même à repris les tags de javadoc et en a ajouté d'autres.

  • # vendredi powered

    Posté par  . Évalué à 5.

    >je suis obligé de reprendre chaque étape de chaque action, de noter
    >sur un papier la liste d'appels de fonctions, les noms de variables, la
    >liste des dépendances... et c'est usant

    C'est à dire qu'avec un langage évolué et un ide récent, c'est le genre de truc qui est fait par la machine et pas par l'homme : c'est plus rapide, c'est toujours à jour et ça permet de consacrer son temps à des trucs plus interressants.

    • [^] # Re: vendredi powered

      Posté par  (site web personnel) . Évalué à 2.

      un langage évolué et un ide récent

      genre ?

    • [^] # Re: vendredi powered

      Posté par  (Mastodon) . Évalué à 8.

      bien sûr, un IDE va comprendre ce que ton code fait, en analysant avec son cerveau positronique, et faire un cours avec présentation sur vidéo-projecteur pour le prochain développeur à se pencher sur chacun de tes bouts de code.

      Il répondra même aux questions. En soixante-sept langues, trente-quatre dialectes, quarante-sept idiomes, et deux-cent-trente-huit variantes locales ou argotiques.

      Yth.

    • [^] # Re: vendredi powered

      Posté par  . Évalué à 1.

      en php ?
      en mod_python ? (moins de pb en python évidement)
      en javascript ?
      en tal ?

      et quand bien même... c'est chiant de devoir en arriver là non ?

  • # Ça pourrait être pire ..

    Posté par  (site web personnel) . Évalué à 5.

    Ça pourrait être du code fermé ...
    Moi par exemple, cette semaine, je dois utiliser une bibliothèque Java qui m'est fournie dans une application que je développe. Évidemment, je n'ai pas accès au code, j'ai juste le droit à une javadoc, et un fichier au format Microsoft Word qui décrit le bouzin. Première bonne surprise, le fichier en question contient un schéma d'architecture plutôt léger et visiblement faux, deux trois paragraphes probablement écrits par quelqu'un qui n'a pas participé au codage de la bibliothèque (et sans doute avant qu'elle existe) et plusieurs page de description de l'API qui ressemble à la javadoc, mais en moins complet.

    La javadoc, doxygen et leurs copains, c'est bien à condition que l'on décrive un minimum les API. Hors la je n'ai que des choses du genre :

    AuthorizeUser : Authorize the user.


    et bien souvent avec des noms moins explicites.

    Finalement, pour comprendre quelque chose, et pour vérifier mes suppositions, j'ai décompilé le code. Ce n'est pas parfait, mais ça aide bien ! Une chance qu'ils n'aient pas pensé à l'obfusquer.

    • [^] # Re: Ça pourrait être pire ..

      Posté par  . Évalué à 1.

      Ca me rappelle une des mes expériences. J'ai récupéré un projet d'interfaçage avec un soft d'un très gros éditeur de logiciels financiers.

      La doc : un gros PDF qui ressemble à de la javadoc mais qui n'en n'est pas - et ça se voit, c'est pas à jour. Quand je demande la javadoc, on me dit "oui oui", mais ça ne vient jamais.

      Je me dis que je vais la générer moi-même en décompilant la lib, mais pas de chance, elle est obfusquée. Du coup, lorsque je croise des bugs, la pile d'appel n'apporte aucune information utile que je puisse transmettre à leur support...

      Et comme il n'ont pas respecté les conventions java (les méthodes commencent par une majuscule, les paramètres par des "p", etc.), la complétion ne marche plus dès que je tape le premier caractère d'une méthode (sauf si je pense à la taper en majuscule bien sûr).

      Ils ont développé leur propre mini-framework de logging qui est compatible avec rien, et d'ailleurs ils ne l'utilisent pas toujours, ça va des fois directement dans SystemOut.

      Que du bonheur...

      Et il y en a encore : un système de licence contraignant et inutile, un "bugzilla" antédilluvien et bien sûr maison, une compatibilité avec uniquement certaines versions de JVM (java 1.4 maxi), etc.

    • [^] # Re: Ça pourrait être pire ..

      Posté par  . Évalué à 1.

      Si ça peut- t'aider, ça ce décompile très bien le Java.

      Tu perds entre autre les commentaires... mais comme dit un peu partout ici, ils sont rarement intéressants de toute façon.

      • [^] # Re: Ça pourrait être pire ..

        Posté par  . Évalué à 7.

        Pardon... Je sors chercher des orties pour me flageller en répétant qu'il faut tout lire avant de répondre.

  • # if (i = 0) // je vérifie que i est égal à 0

    Posté par  . Évalué à 6.

    D'expérience (professionnelle), les commentaires ne sont jamais mis à jour en même temps que le code. Ils sont donc généralement faux.

    Notons par ailleurs qu'aucun compilateur (de ma connaissance) ne vérifie que les commentaires sont exacte. J'en ai vu de nombreux qui décrivait autre chose que le code correspondant. (cf le titre)

    J'en ai déduit qu'on doit trouver en commentaire la fonction d'un programme/fonction, la description de ses paramètres et valeurs de retour, des exceptions, bugs et limites. Eventuellement une référence à l'algorithme utilisé si c'est pas évident.
    MAIS surtout JAMAIS de description du code.
    Si c'est bien codé, c'est lisible.

  • # No comments !

    Posté par  . Évalué à 4.

    Si la machine s'y retrouve, c'est que le programmeur a les moyens de s'y retrouver. Code==Doc.
    Il existe des IDEs qui se démerdent avec le code qu'on leur vomit pour faire la moitié de ce que tu demandes.

  • # Faites du Lisp

    Posté par  . Évalué à 5.

    et pas de ses pseudos langages et vous verrez que plus jamais vous ne vous poserez de questions sur le pourquoi du comment de la chose.

  • # Moi ce que je fais ...

    Posté par  . Évalué à 4.

    Quand je code en C je fais trois types de fichiers :
    un .h un .c et un .d pour "documentation" qui a le même principe que
    les .c sauf qu'au lieu d'implémenter les prototypes il explique les spécifications, raison d'être de la fonction et quelques petits exemples.

    Comme ça quand je navigue dans le .c j'ai pas des millions de commentaires qui embrouillent le bazar, et quand je veux savoir ce que fait une fonction, je dois pas bouger jusqu'a sa définition.

    Bon maintenant il me reste à faire un plugin vim qui va chercher automatiquement la doc de la fonction et ça sera le pied.

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.