“Les commentaires sont une odeur de code” [fermé]

Un de mes collègues estime que toute utilisation de commentaires dans le code (c.-à-d. Sans méthode de style javadoc ni commentaires de classe) est une odeur de code . Qu'est-ce que tu penses?

Seulement si le commentaire décrit ce que fait le code.

Si je voulais savoir ce qui se passait dans une méthode ou un bloc, je lisais le code. J'espère de toute façon que tous les développeurs travaillant sur un projet donné sont au moins suffisamment familiarisés avec le langage de développement pour lire ce qui est écrit et comprendre ce qu'il fait.

Dans certains cas d'optimisation extrême, vous pouvez utiliser des techniques qui rendent difficile la tâche de suivre ce que votre code est en train de faire. Dans ces cas, les commentaires peuvent et doivent être utilisés non seulement pour expliquer pourquoi vous avez de telles optimisations, mais également pour ce que fait le code. En règle générale, demandez à une autre personne (ou à plusieurs autres personnes) de connaître le langage et le projet d’implémentation et examinez votre code - si elle ne comprend pas à la fois le pourquoi et le comment, vous devez commenter le pourquoi et le le comment

Cependant, ce qui n'est pas clair dans le code, c'est pourquoi vous avez fait quelque chose. Si vous adoptez une approche qui pourrait ne pas être évidente pour les autres, vous devriez avoir un commentaire expliquant pourquoi vous avez pris les décisions que vous avez prises. J'imagine que vous ne réaliserez peut-être même pas qu'un commentaire est nécessaire avant quelque chose comme une révision de code, où les gens veulent savoir pourquoi vous avez fait X au lieu de Y - vous pouvez capturer votre réponse dans le code pour tous ceux qui l'examinent. A l'avenir.

La chose la plus importante, cependant, est de modifier vos commentaires lorsque vous modifiez votre code. Si vous modifiez un algorithme, veillez à mettre à jour les commentaires en indiquant pourquoi vous avez opté pour l'algorithme X sur Y. Les commentaires obsolètes dégagent une odeur de code encore plus grande.

Ceci est particulièrement irritant à entendre pour le moment. J'ai passé quelque temps ce week-end à regarder du code très bien nommé, très propre et sans commentaire implémentant un algorithme de recherche (un algorithme qui n'est pas réellement publié). Je suis au courant de cela, le gars assis à côté de moi était l'inventeur, et le code a été écrit il y a quelques années par quelqu'un d'autre. Nous pouvions à peine le suivre.

Votre collègue n'est pas assez expérimenté, évidemment.

Les commentaires devraient expliquer pourquoi, pas comment.

HowLes commentaires de type sont généralement mieux traités avec la refactorisation. Personnellement, j'évite généralement les commentaires favorables à la refactorisation.

Avant:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

après:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Je déclare votre collègue un hérétique! Où sont mes bottes brûlantes hérétiques?

Obsessionnels commentant est mauvais et un mal de tête d'entretien, et les commentaires ne remplacent pas les méthodes bien nommées, des classes, des variables, etc. Mais parfois mettre pourquoi quelque chose est la façon dont il est peut être extrêmement précieux pour l'idiot pauvre qui doit maintenir le code dans six mois - en particulier quand ce pauvre idiot finit par être toi.

Quelques commentaires du code sur lequel je travaille:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

Idéalement, le code devrait être si bien codé qu'il devrait être auto-explicatif. Dans le monde réel, nous savons qu’un code de très haute qualité nécessite parfois des commentaires.

Ce qu'il faut absolument éviter, c'est la "redondance des commentaires" (commentaires qui n'ajoutent rien au code):

i++; // Increment i by 1

Ensuite, s’il existe une bonne conception du code (et maintenu / aligné), les commentaires sont encore moins utiles.

Mais dans certaines circonstances, les commentaires peuvent être une aide précieuse pour la lisibilité du code:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

N'oubliez pas que vous devez gérer et synchroniser également les commentaires ... les commentaires obsolètes ou erronés peuvent être une douleur terrible! Et, en règle générale, trop de commentaires peut être le symptôme d'une mauvaise programmation.

Définir catégoriquement une méthode ou un processus en tant qu '"odeur de code" est une "odeur de fanatisme". Le terme devient le nouveau "considéré comme nuisible".

S'il vous plaît rappelez-vous que toutes ces choses sont supposées être des directives.

Bon nombre des autres réponses donnent de bons conseils quant au moment où les commentaires sont justifiés.

Personnellement j'utilise très peu de commentaires. Expliquez le but de processus non évidents et laissez la menace de mort occasionnelle à quiconque pourrait envisager de modifier lui-même des choses qui nécessitaient des semaines de réglage.

Refacturer tout jusqu'à ce qu'un enfant d'âge maternelle puisse comprendre que ce n'est probablement pas une utilisation efficace de votre temps et ne fonctionnera probablement pas aussi bien qu'une version plus concise.

Les commentaires n'affectant pas le temps d'exécution, le seul problème à prendre en compte est la maintenance.

Dans certains cas, aucune bonne désignation, refactoring, etc. ne peut remplacer un commentaire. Il suffit de regarder cet exemple du monde réel (la langue est Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Ça a l'air étrange, n'est-ce pas? Probablement une erreur de copier / coller? Crie pour un bug?

Maintenant la même chose avec les commentaires:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

Le problème principal ici est la signification du terme "odeur de code".

De nombreuses personnes (y compris vous, je pense) comprennent qu'une odeur de code ressemble à une erreur ou, du moins, à une correction. Vous pensez peut-être que cela est synonyme d’anti-pattern.

Ce n'est pas le sens du terme!

La métaphore de l'odeur du code provient de Wards Wiki , et ils soulignent:

Notez qu'un CodeSmell est un indice que quelque chose pourrait être faux, pas une certitude. Un idiome parfaitement bon peut être considéré comme un code parce qu'il est souvent mal utilisé ou qu'il existe une alternative plus simple qui fonctionne dans la plupart des cas. Appeler quelque chose comme CodeSmell n'est pas une attaque. c'est simplement un signe qu'un regard plus attentif est justifié.

Alors qu'est-ce que ça veut dire que les commentaires sont une odeur de code: cela signifie que quand vous voyez un commentaire, vous devriez faire une pause et penser: "Hmmm, je sens un indice que quelque chose pourrait être amélioré". Peut-être que vous pouvez renommer une variable, effectuer la méthode "extract method" -refactoring - ou peut-être que le commentaire est en fait la meilleure solution.

C’est ce que cela signifie pour les commentaires d’être des codes qui sentent.

EDIT: Je suis tombé sur ces deux articles, ce qui explique mieux que moi:

• Excuses dans le code
• Pour avoir besoin de commentaires

Je pense que la règle est assez simple: imaginez un inconnu complet en train de voir votre code. Vous serez probablement étranger à votre propre code dans 5 ans. Essayez de minimiser l'effort mental pour comprendre votre code pour cet étranger.

Une bonne idée pour avoir les bons commentaires est de commencer par écrire des commentaires.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Cela vous permet d'extraire facilement des méthodes pour même vous débarrasser des commentaires,
laissez simplement le code dire ces choses ! Voyez comment cela est réécrit (couper / coller) de manière très agréable:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Pour les choses qui ne peuvent pas être séparées, n'extrayez pas les méthodes et ne tapez pas le code sous les commentaires.

C’est ce que je considère comme un moyen utile de réduire au minimum les commentaires. C’est vraiment inutile de commenter chaque ligne ... Documentez une seule ligne uniquement s’il s’agit d’une initialisation de valeur magique ou lorsque cela a du sens.

Si les paramètres sont trop utilisés, ils doivent alors être des membres privés de votre classe.

Je pense que la réponse est l'habituel "Cela dépend". Commenter le code juste pour commenter le code est une odeur. En commentant le code parce que vous utilisez un algorithme obscur qui est un ordre de grandeur plus rapide, le programmeur de maintenance (généralement six mois après que je l'ai écrit) enregistre une demi-journée de fouille dans le code pour déterminer ce qu'il fait.

// Dear me in the future. Please, resolve this problem.

ou

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

Les commentaires de code ne sont certainement pas une "odeur de code". Cette croyance découle généralement du fait que les commentaires peuvent devenir obsolètes (désuets) et difficiles à conserver. Cependant, avoir de bons commentaires expliquant pourquoi le code fait quelque chose d'une certaine manière peut (et est généralement) important pour la maintenance.

Les bons commentaires permettent de comprendre plus facilement ce que fait le code et, plus important encore, pourquoi il le fait de manière particulière. Les commentaires sont destinés à être lus par les programmeurs et doivent être clairs et précis. Un commentaire difficile à comprendre ou inexact n'est pas mieux que de n'avoir fait aucun commentaire.

Ajouter des commentaires clairs et précis à votre code signifie que vous n’avez pas besoin de vous fier à la mémoire pour comprendre le «quoi» et le «pourquoi» d’une section de code. Ceci est particulièrement important lorsque vous consultez ce code ultérieurement, ou que quelqu'un d'autre le vérifie. Dans la mesure où les commentaires font partie du contenu textuel de votre code, ils doivent respecter les principes de rédaction appropriés en plus d'être clairement écrits.

Pour rédiger un bon commentaire, vous devez faire de votre mieux pour documenter l'objectif du code (le pourquoi, pas comment) et indiquer le raisonnement et la logique qui sous-tendent le code aussi clairement que possible. Idéalement, les commentaires doivent être écrits en même temps que le code. Si vous attendez, vous n'allez probablement pas revenir en arrière et les ajouter.

Sams Teach Yourself Visual C # 2010 in 24 Hours , pp 348-349.

Si le code a été écrit d'une manière particulière pour éviter un problème présent dans une bibliothèque (à la fois une bibliothèque tierce ou une bibliothèque fournie avec le compilateur), il est logique de le commenter.
Il est également judicieux de commenter le code devant être modifié dans les versions futures, lors de l’utilisation d’une nouvelle version d’une bibliothèque, ou lors du passage de PHP4 à PHP5, par exemple.

Même le livre le mieux écrit a encore probablement une introduction et des titres de chapitre. Les commentaires dans du code bien documenté sont toujours utiles pour décrire les concepts de haut niveau et expliquer comment le code est organisé.

Une mention honorable est l'anti-pattern:

J'ai l'impression que, parfois, les préamplis de licence FLOSS sont fréquemment utilisés à la place de la documentation de fichier. La GPL / BSDL crée un joli texte de remplissage, et après cela, vous voyez rarement un autre bloc de commentaires.

Je ne suis pas d'accord avec l'idée qu'il est mauvais d'écrire des commentaires pour expliquer le code. Cela ignore complètement le fait que le code contient des bogues. On pourrait voir clairement ce que le code fait sans commentaires. Ce que le code est censé faire est moins clair . Sans commentaires, comment savoir si les résultats sont erronés ou s'ils sont utilisés de manière incorrecte?

Les commentaires doivent expliquer l’ intention du code, de sorte que, s’il ya erreur, une personne qui lit les commentaires + code a une chance de le trouver.

Je me retrouve généralement à écrire des commentaires en ligne avant d’ écrire le code. De cette façon, il est clair que j'essaye d'écrire du code et réduit le risque d'être perdu dans un algorithme sans vraiment savoir ce que vous essayez de faire.

Les commentaires qui ont été ajoutés parce que quelqu'un pense qu'il est acceptable d'avoir 700 lignes dans une méthode sont une odeur.

Les commentaires qui sont là parce que vous savez que si vous ne mettez pas de commentaire, quelqu'un commettra la même erreur encore une fois, ce sera une odeur.

Les commentaires insérés parce que certains outils d'analyse de code l'exigent sont également une odeur.

Les personnes qui n'écriront jamais de commentaires ou n'écriront même pas un petit coup de pouce pour les autres développeurs auront aussi une odeur. Je suis étonné de voir combien de personnes n'écriront rien, mais se retourneront ensuite pour reconnaître qu'elles ne peuvent pas se souvenir de ce qu'elles ont fait il y a trois mois. Je n'aime pas écrire des documents, mais j'aime avoir à dire encore et encore aux gens la même chose encore moins.

Je vais répondre avec une question à moi. Pouvez-vous trouver le bogue dans le code non commenté ci-dessous?

tl; dr: La prochaine personne à entretenir votre code pourrait ne pas être aussi divin que vous.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Vous devez garder un équilibre entre le code et les commentaires ... Habituellement, j'essaie d'ajouter des commentaires qui résument un bloc de code. Non pas parce que je ne pourrai pas comprendre le code (enfin, ça aussi), mais parce que je peux lire plus rapidement mon propre code et localiser des sections spécifiques où se trouve l'essentiel.

Quoi qu'il en soit, mes critères personnels sont "en cas de doute, commentez". Je préfère avoir une ligne redondante qu'une ligne complètement cryptique que je ne pourrai pas comprendre. Je peux toujours supprimer les commentaires sur une révision de code, après un certain temps (et c'est généralement le cas)

En outre, les commentaires sont très utiles en ajoutant des "mises en garde" comme "Faites attention! Si le format de l'entrée n'est pas ASCII, ce code devra changer!"

En lisant ceci, cela me rappelle quelque chose que j’avais lu pour la première fois (d’une liste plus longue, conservée par photocopies) il ya quelques décennies:

Les vrais programmeurs n'écrivent pas de commentaires - si c'était difficile à écrire, ce devrait être difficile à lire

Une odeur un peu plus âgée me semble.

Je pense que les commentaires de code ont un très mauvais départ dans la vie. Je ne sais pas à propos de ces jours-ci, mais lorsque l’on m’enseignait la programmation à l’école, j’ai reçu des devoirs du type "Écris un programme qui affiche les nombres de un à dix sur des lignes séparées. Assurez-vous de commenter votre code." Si vous n’ajoutiez pas de commentaires, vous seriez mal notés, car commenter votre code est une bonne chose.

Mais qu'y a-t-il à dire sur un processus aussi trivial? Donc vous finissez par écrire le classique

i++; // add one to the "i" counter.

juste pour obtenir une note décente et, si vous en avez un, vous créez instantanément une très faible opinion des commentaires de code.

Commenter le code n'est pas une bonne chose. C’est quelque chose de nécessaire, et Thomas Owens, dans la réponse au haut de la page, fournit une excellente explication des situations dans lesquelles il est nécessaire. Cependant, ces situations se produisent rarement dans les travaux de type devoirs.

À bien des égards, l'ajout d'un commentaire devrait être considéré comme un choix de dernier recours, lorsque ce qui doit être dit ne peut pas être dit clairement dans les parties actives du langage de programmation. Bien que la dénomination des objets puisse devenir obsolète, divers mécanismes d’absence de retour d’informations (humain et ordinateur) facilitent l’oubli du maintien des commentaires. Par conséquent, les commentaires s’étalent beaucoup plus rapidement que le code actif. Pour cette raison, lorsqu'un choix est possible, il convient de toujours préférer modifier le code pour le rendre plus clair que d'annoter un code peu clair avec des commentaires.

Bien sûr, les commentaires sont une odeur de code ...

chaque programmeur sait que nous finissons tous par devenir fous à cause de la quantité de travail, de débogage ou simplement de la folie que nous rencontrons.

"Fais ça!" dit votre chef de projet.

Vous répondez: "Cela ne peut pas être fait."

Ils disent: "Ensuite, nous trouverons quelqu'un d'autre pour le faire."

Vous dites: "OK, peut-être que cela peut être fait."

Et ensuite, passez X jours, semaines, mois… à essayer de le comprendre. Tout au long du processus, vous allez essayer et échouer, et essayer et échouer. Nous faisons tous cela. La vraie réponse est qu'il y a deux types de programmeurs, ceux qui commentent et ceux qui ne le font pas.

1) Ceux qui le font facilitent leur propre travail en documentant pour référence future, en commentant les routines échouées qui ne fonctionnent pas (l’odeur ne les supprime pas après avoir trouvé celle qui fonctionne.) Ou en rompant le code avec des commentaires. Nous espérons que le formatage le rendra un peu plus facile à lire et à comprendre. Sérieusement, je ne peux pas leur en vouloir. Mais à la fin, ils se cassent et puis vous avez ceci: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Ceux qui ne le font pas prétendent être un super-héros ou vivent dans une grotte . Ils ont simplement eux-mêmes un mépris inconsidéré pour les autres et se moquent bien du code ou de la signification que cela pourrait avoir pour plus tard.

Maintenant, ne vous méprenez pas… les variables et les fonctions auto-documentées peuvent éviter ce problème… et croyez-moi, vous ne pourrez jamais nettoyer suffisamment de code. Mais la vérité est que tant que vous conservez des sauvegardes, vous pouvez TOUJOURS supprimer des commentaires.

Je dirais que ne pas utiliser certains commentaires dans votre code est une odeur de code. Bien que je convienne que le code doit être auto-documenté autant que possible, vous atteignez un certain point où vous allez voir du code qui n'a aucun sens, quelle que soit la qualité de l'écriture du code. J'ai vu du code dans des applications métier où les commentaires sont à peu près obligatoires car:

1. Vous devez faire quelque chose au cas par cas et il n'y a pas de bonne logique pour cela.
2. Le code changera probablement dans un an ou deux lorsque les lois seront modifiées et que vous souhaitez le retrouver rapidement.
3. Quelqu'un a modifié le code par le passé, car il ne comprenait pas ce qu'il faisait.

En outre, les guides de style de l'entreprise peuvent vous indiquer de faire quelque chose d'une certaine manière. S'ils disent que vous pourriez avoir des commentaires décrivant les blocs de code d'une fonction, incluez-les.

Il existe une grande différence fondamentale entre les commentaires et le code: les commentaires sont un moyen pour les personnes de communiquer des idées à d'autres personnes, alors que le code est principalement destiné à l'ordinateur. Le "code" comporte de nombreux aspects qui ne concernent que les humains, comme la dénomination et l'indentation. Mais les commentaires sont écrits strictement pour les humains, par les humains.

Par conséquent, écrire des commentaires est aussi difficile que toute communication humaine écrite! L’écrivain doit avoir une idée claire de l’audience et du type de texte dont il aura besoin. Comment savoir qui lira vos commentaires dans dix ou vingt ans? Et si la personne est d'une culture complètement différente? Etc. J'espère que tout le monde comprend cela.

Même à l'intérieur de la petite culture homogène dans laquelle je vis, il est tellement difficile de communiquer des idées à d'autres personnes. La communication humaine échoue généralement, sauf par accident.

Je suis d'accord avec votre collègue. Je dis toujours que si je commente mon code, cela signifie que je suis inquiet que je ne serai pas en mesure de comprendre mon propre code à l'avenir. C'est un mauvais signe.

La seule autre raison pour laquelle j'ajoute des commentaires dans le code est d'appeler quelque chose qui n'a pas de sens.

Ces commentaires prennent généralement la forme de quelque chose comme:

//xxx what the heck is this doing??

ou

// removed in version 2.0, but back for 2.1, now I'm taking out again

Les commentaires de code donnant, le cas échéant, des unités d’arguments et de retours de fonction, des champs de structure, même des variables locales, peuvent s’avérer très utiles. Rappelez-vous l'orbiteur de Mars!

Voici ma règle d'or:

• Écrivez le code et stockez un court résumé du code dans un document séparé.
• Laissez le code seul pendant plusieurs jours pour travailler sur autre chose.
• Retournez au code. Si vous ne comprenez pas immédiatement ce qu'il est censé faire, ajoutez le résumé au fichier source.

Renseignez votre collègue sur la technique de programmation alphabète .

Non, les commentaires ne sont pas une odeur de code, ils sont simplement un outil qui peut être utilisé de manière abusive.

Exemples de bons commentaires:

// Je pense que c'est en cm. Une enquête plus approfondie est nécessaire!

// C'est une façon intelligente de faire X

// La liste est garantie d'être non vide ici