Journal çà sert a rien les commentaires

Posté par  (site web personnel) .
Étiquettes : aucune
0
26
mar.
2004
pour nourrir le troll (http://linuxfr.org/~jcs/10947.html(...)), j'expose mon point de vue:

Les commentaires çàpueçàsertarien !
pourquoi ? parce qu'on ajoute des commentaires si le code n'est pas clair! dans ce cas il faudrait mieux clarifier le code non ?

changer le nom des fonction/variables, decouper en plus de fonction pour decouper le code...

** plutot que:
// faire un truc
[...]
// faire un autre truc
[...]

**
faireUnTruc();
faireUnAutreTruc();

** plutot que:

for(i=0;i<1024;i++) {}

**
for( numeroDeFace=0; numeroDeFaces<nombreDeFaces; numeroDeFaces++ ) {}


des commentaires sur un code crade çà ne rend pas le code propre !

ps: bien sur il faut documenter dans les entetes, les fonctions et leurs parametres, et ne pas hesiter a expliquer un algo...

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 2.

    mouarf fonction_qui_prend_en_parametre_l_age_du_capitaine_et_qui_retourne_la_taille_de_son_bateau($gnagnagna)

    comment ça je nourris le troll!!!

    ha je dois partir.

    je refuse!!!

    Je trolle dès quand ça parle business, sécurité et sciences sociales

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 1.

      get_ship_size_by_captain_age($age); ?
      voir même $ship->getSizeByCaptainAge($age);

      ça va c'est pas encore trop la mort comme nom de fonction, et je preferre ça que d'ajouter un /* cette fonction récupère la taille du bateau en fonction de l'age du capitaine */ qui est beaucoup plus verbose pour pas grand chose de plus (s/pas\ grand\ chose/rien ?).

      :>

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 3.

      fonction Calcul_taille_bateau_suivant_age_capitaine (Age_du_Capitaine : in Age) return Taille;

      Savoir bien nommer et de manière simple les différents objets d'un est aussi important que le reste. Plus c'est simple, mieux c'est (comme pour la conception).

      Par contre pour la pérénité de mon travail, je ferais plutôt
      int TBat (int : ACap) { ... }
      Comme cela moi seul peux le relire.

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 1.

    Mouais...
    Détailler quand même toutes les 10 lignes d'un bloc de code où l'on en est par exemple, c'est utile si le bloc fait 200 lignes (oui on doit le couper en fonctions...)
    En fait, lors d'une opération simple mais longue, c'est utile pour savoir l'état de la progression...

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 2.

      Justement, tout le piége est là. Pour être lisible, une fonction/procédure ne doit pas contenir plus de 20~30 instructions. Si ta fonction est grosse, tu la découpes. En plus, c'est plus simple à maintenir.

      • [^] # Re: çà sert a rien les commentaires

        Posté par  . Évalué à 2.

        une fonction/procédure ne doit pas contenir plus de 20~30 instructions. Si ta fonction est grosse, tu la découpes. En plus, c'est plus simple à maintenir.

        Je n'aime pas trop ce "dogme", il se discute, je trouve.

        Je préfère parfois une grosse fonction que plusieurs petites, à laquelle il va falloir passer des arguments. Même pour une simple relecture, c'est pas toujours évident de sauter d'un appel de fonction à l'autre, avec en plus les données qui changent de nom entre l'appelant et l'appelé.

        • [^] # Re: çà sert a rien les commentaires

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

          c'est pas toujours évident de sauter d'un appel de fonction à l'autre

          Ctrl-] et Ctrl-T (dans vim) sauvent la mise. :)

          • [^] # Re: çà sert a rien les commentaires

            Posté par  . Évalué à 2.

            F12 et Ctrl-* dans Visual Studio aussi. Mais je ne parle pas d'une des fonctionnalités basiques d'un environnement de développement digne de ce nom, je parle de la difficulté à changer de contexte pour le lecteur "humain". Bien sûr, quand on ne veut pas lire tout le code, les fonctions c'est pratique : il suffit de ne pas aller les lire. Mais si on doit tout lire, je préfère encore que tout le code soit dans un seul bloc.

            Enfin, comme je disais, ça se discute ; il y a aussi des cas où c'est préférable d'avoir plusieurs petites fonctions. C'est juste que je n'aime pas le côté "il FAUT faire des fonctions"

            • [^] # Re: çà sert a rien les commentaires

              Posté par  . Évalué à 1.

              Faire des fonctions pour faire des fonctions, c'est sûr ca ne sert à rien.

              Cependant si les fonctions sont bien découpées (ex une fonction pour une tache précise), ca permet en cas de relecture de code de lire uniquement la partie qui t'intéresse. Je préfère lire ce genre de code:

              faire_ceci(a);
              faire_cela(b);

              plutot que le code correspondant à faire_ceci et faire_cela en un seul bloc.

              Dans le cas ou le bug est dans faire_cela, je n'ai pas à relire faire_ceci.

              Si je veux comprendre le fonctionnement d'un programme je sais que faire_ceci est censé faire ceci, et je ne m'occupe pas forcément dans l'immédiat de _comment_ il le fait. Je peux y revenir lorsque j'ai une idée globale du fonctionnement du programme.

        • [^] # Re: çà sert a rien les commentaires

          Posté par  . Évalué à 1.

          « Je préfère parfois une grosse fonction que plusieurs petites, à laquelle il va falloir passer des arguments. »

          On n'est jamais obligé de passer des arguments, tu places tes variables locales au module, quitte à faire un module pour ça. ("module" à remplacer en fonction du langage).

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 8.

    Les commentaires ne servent pas à grand chose quand on est dessus tout le temps. Le jour où on y revient après quelques temps ou que quelqu'un se penche dessus ... vive les commentaires, plus y'en a mieux c'est.

    Comme dit Aimé Jacquet "ça ne coute pas plus cher de bien manger".

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 1.

    for( numeroDeFace=0; numeroDeFaces<nombreDeFaces; numeroDeFaces++ ) {}

    C'est une technique bien connu du codage auto-commenté.
    C'est une trés bonne méthode si tu codes tout seul. Par contre si tu dois fournir une libraire à quelqu'un, il souhaitera avoir un fichier entête avec une documentation précise de chaque fonction et chacun de ses paramètres.
    Remarque, le top c'est de faire les deux !

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 2.

      c'est ce qu'il dit !
      "ps: bien sur il faut documenter dans les entetes, les fonctions et leurs parametres, et ne pas hesiter a expliquer un algo..."

  • # Re: çà sert a rien les commentaires

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

    Les commentaires, ça sert à expliquer le pourquoi, pas le comment. Aucun code source ne te permettra de comprendre le pourquoi. (Et puis de temps en temps, quand tu ponds du code de sioux, un petit comment ne peut pas faire de mal, pour le mec moins doué que toi qui viendra essayer de corriger un bug plus tard.)

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 0.

      Quoi ?
      Il y a encore des programmeurs qui créent des bugs ???

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 1.

      Faut lire... c'est exactement ce qu'il dit : les commentaires -> en en-tête des fonctions, modules, etc. mais pas au sein du code.

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 2.

      Je plussoierais .. si je pouvais ...
      En effet, le commentaires ne sont pas la pour décrire ce que l'on fait mais pourquoi on le fait ...

      Imagine un algo qui contrôle la validité d'une date; dans le cas des années non bissextiles, on va refuser les 29 février, ton code sera donc du type

      /* on refuse le 29/02 si on n'est pas bissextile */
      SI (annee NON bissextile ET jour>28 ET mois==2 )
      ALORS retourne ERROR;

      Et bien dans ce cas, le commentaire explique le "pourquoi métier".
      Pour cet exemple, tout le monde sait que seules les années bissextiles possèdent un 29/02, mais dans une appli métier, tu ne peux présupposer des connaissances métier des futurs codeurs, d'où une explication nécessaire dans le commentaire.

      • [^] # Re: çà sert a rien les commentaires

        Posté par  . Évalué à 1.

        /* on refuse le 29/02 si on n'est pas bissextile */
        SI (annee NON bissextile ET jour>28 ET mois==2 )
        ALORS retourne ERROR;

        Bref, on dit en français ce que fait le code. Ca permet de lire les sources rapidement en ne lisant que les commentaires.
        Pour moi c'est un commentaire "QUOI". Il en faut, et je trouve qu'ils rendent le code plus agréable à lire.

        Les commentaires "POURQUOI et COMMENT" ont à mon avis plus leur place dans des grosses cartouches en tête de fichier ou de fonction.

        • [^] # Re: çà sert a rien les commentaires

          Posté par  . Évalué à 2.

          SI (est_bissextile(jour, mois, annee)) ALORS retourne ERROR;

          se passe de commentaire...

          • [^] # Re: çà sert a rien les commentaires

            Posté par  . Évalué à 2.

            C'est domage, vu que c'est un code incompréhensible.

            C'est une erreur si ta fonction renvoie une valeur non nulle quand on lui passe 29, 2 et 2004 ?

            • [^] # Re: çà sert a rien les commentaires

              Posté par  . Évalué à 1.

              « C'est domage, vu que c'est un code incompréhensible. »

              Non. Tout ce qu'il y a à savoir sera dans l'entete de la fonction qui contient ça.

  • # Re: çà sert a rien les commentaires

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

    Une référence là dessus :

    http://mindprod.com/unmaindocumentation.html(...)

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 2.

      OUI!!!!!!
      How to write unmaintainable code
      Un grand classique (pour moi en tout cas)
      Un des textes les plus drôles et constructifs qui soit. Franchement, je l'ai lu j'ai cru que j'allais m'étouffer tellement je rigolais et puis ce texte est resté comme un parfait catalogue des choses à ne pas faire. J'y pense tout le temps.
      Une sorte d'Anti-pattern mais en plus drôle!
      Mangez-en!!

      (ça va j'en ai pas trop fait?)

      (ça c'était un commentaire inutile)

      (ça c'était aussi un commentaire inutile)

      (ça c'était aussi un commentaire inutile)

      (ça c'était aussi un commentaire inutile)
      .
      .
      .
      A++

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 8.

    Les commentaires peuvent aussi servir à autre chose. Exemple:

    // Mais où as-tu la tête. C'est pas beau ça. Va au dodo et reviens demain quand tu auras retrouvé tes esprit.

    // Si vous relisez ce code: prévoyiez une aspirine.

    // Changelog:
    // *26/04/04 : Ajout de commentaires

    // Rappel: Faut que tu paye ta facture de téléphone

    // crac crac time. dsl je finirai demain.

    // Bon en C, les tableaux commencent à 0

    // Ctrl-s pour sauvegarder et à faire souvent.

    // Blague: (ça détend)
    // C'est un ptit pois qui va à la boulangerie et demande: "Bonjour, je voudrai deux baguettes"
    // La boulangère: "Désolé, il ne me reste plus que des pains."
    // le ptit pois: "Ha bin, ça fait rien, je suis en mobylette."
    // !!!!

    // SuseCaPuPlus.CestLibre

    // pour les commentaires CF: http://linuxfr.org/~kassoulet/10959.html(...)

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 1.

      Ha j'oubliais quelques chose:

      // pour mettre un peu de couleurs. C'est plus gai comme ça. (sous un éditeur qui colorise le code bien sur).

  • # Re: çà sert a rien les commentaires

    Posté par  . Évalué à 1.

    for( numeroDeFace=0; numeroDeFaces<nombreDeFaces; numeroDeFaces++ ) {}

    C'est bien beau ça, mais là on sait juste qu'on passe sur toutes les faces, on ne sait pas quel traitement on fait dessus, et c'est pour ça qu'un commentaire serait bienvenu juste au dessus du for, pour dire voire expliquer quel traitement on fait.

    En fait il faudrait commenter non pas pour dire ce que chaque ligne fait, mais ce que chaque bloc de 3-4 lignes fait, en une phrase simple.

    Exemple pas bon :
    /* mettre 5 dans l'age de toto */
    toto.age = 5;
    /* mettre "toto" dans le nom de toto */
    toto.nom = "toto"

    Exemple bon :
    /* preparer les donnees de la fiche de toto */
    toto.age = 5;
    toto.nom = "toto"

    Cela dit, il est évident que des noms de variable bien choisis aident énormément à la relecture du code. Et il ne faut pas avoir peur d'utiliser des longs noms de variable/fonction, ne jamais les abréger, ça les rend illisible !

    Exemple pas bon :
    /* initialise l'age de toto */
    sta(age);

    Exemple bon :
    /* initialise l'age de toto et calcule l'annee de naissance */
    set_toto_age(age);

    Ici, les commentaires peuvent en plus informer l'utilisateur sur un traitement que fait la fonction et qui ne transparait pas de façon évidente dans le nom de la fonction, même si cela reste logique par rapport au traitement.

    • [^] # Re: çà sert a rien les commentaires

      Posté par  . Évalué à 1.

      « Exemple bon :
      /* initialise l'age de toto et calcule l'annee de naissance */
      set_toto_age(age); »

      C'est du même niveau que « mettre 5 dans l'age de toto ». Ce commentaire devrait être inutile si
      - le commentaire du module ou de la fonction est complet
      - le module ou la fonction n'est pas trop long

      S'il y a besoin d'un tel commentaire, c'est qu'un de ces deux points ne va pas du tout...

Suivre le flux des commentaires

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