Commentaire avant ou après le code correspondant
En supposant qu'un commentaire ne rentre pas (ou ne peut pas aller) sur la ligne à laquelle il s'applique, doit-on écrire le commentaire avant le code ou après?
Eh bien, partout où les futurs lecteurs comprendront le mieux la portée du commentaire. En d'autres termes, partout où la plupart des programmeurs/scripteurs mettent de tels commentaires.
Alors où la plupart des programmeurs/scripteurs mettent-ils un commentaire: avant ou après son code?
Si votre réponse ne s'applique qu'à des langues spécifiques, veuillez indiquer laquelle.
Et si vous pouvez citer une spécification ou un guide accepté qui soutient votre réponse, tant mieux.
Je commenterais en ligne ou avant le code auquel le commentaire devrait s'appliquer. Le sens des commentaires est d'obtenir une compréhension de base de ce que fait le code, sans avoir besoin de lire le code lui-même. Il est donc beaucoup plus logique de placer les commentaires avant le code qu'il décrit.
Microsoft dit que ce serait une bonne pratique de programmation de commencer les procédures avec un petit commentaire. (Ils ne mentionnent pas de commentaires après les procédures) MSDN Le lien concerne VisualBasic mais il s'applique à la plupart des langages de programmation que je pense.
Je préfère que les commentaires soient au-dessus du code auquel ils se réfèrent, il est plus logique de dire à une personne qui lit le code ce qui va arriver plutôt que d'essayer de se référer au code précédent pour expliquer que certaines lignes de code en désordre ont corrigé un bug qui était délicat alors ne le touchez pas.
Je pense que le code est généralement lu de haut en bas. Si rien d'autre, la mémoire musculaire me ferait associer un commentaire à la prochaine ligne de code en dessous.
En règle générale, le commentaire doit être en haut de la ligne suivant la même indentation que le travail. Par exemple, des commentaires au-dessus du corps des fonctions, et un commentaire juste au-dessus du début d'un algorithme critique.
La raison en est que lorsque quelqu'un commence à le lire, il devient évident que la raison pour laquelle quelque chose est fait de cette manière; où comme la personne ne sait pas jusqu'à quel point il faut faire défiler pour la réponse. S'il est au-dessus, c'est juste là pour voir.
Alors, où la plupart des programmeurs/scripteurs mettent-ils un commentaire: avant ou après son code?
Au cours de nombreuses années de programmation utilisant une variété de langues, je ne me souviens pas avoir vu de code dans une langue où un commentaire est placé sur une nouvelle ligne après le code auquel il se réfère. Aux États-Unis, au moins, la norme de facto commente soit avant le code, soit sur la même ligne après le code. Écrire vos commentaires après le code correspondant invite à un test de dépistage de drogue, à une évaluation psychiatrique et/ou à un rendez-vous avec une pince et une torche.
La seule exception à laquelle je peux penser est un commentaire marquant la fin d'une section précédemment commentée, comme ceci:
// BEGIN CRITICAL SECTION
lock(&myMutex);
doSomeThreadUnsafeStuff();
unlock(&myMutex);
// END CRITICAL SECTION
Jef Raskin a écrit un essai réfléchi sur les commentaires qui vaut la peine d'être lu. Il ne dit pas s'il met ses commentaires avant ou après le code, mais il dit qu'il ne les met jamais en ligne, et je parierais beaucoup d'argent qu'il ne les met pas non plus.
Essayez de ne commenter que lorsque c'est vraiment nécessaire; le code devrait essayer d'être auto-documenté autant que possible.
Cela étant dit, le placement peut dépendre: Si vous utilisez une ligne distincte pour le commentaire, mettez-la avant le code réel. Si vous l'avez sur la même ligne, mettez-le après.
// this workaround is required to make the compiler happy
int i = 0;
Vs.
int i = 0; // make the compiler happy
Mais jamais:
int i = 0; // this workaround is required to make the compiler happy
Je ne suis pas vraiment un grand fan de commentaires. Lors d'un cours de génie logiciel, j'ai été initiée à l'idée de code auto-documenté. Le code est la seule documentation correcte garantie à 100% de lui-même - les commentaires doivent être mis à jour, soigneusement construits et pertinents, sinon ce sont des pièges qui peuvent être pires que pas de commentaire. Ce n'est que lorsque j'ai commencé à travailler dans une boutique C++ avec un guide de style strict et des conventions de dénomination significatives que j'ai vraiment intériorisé ce concept.
Parfois, des commentaires sont nécessaires. Souvent, une dénomination prudente des variables, une utilisation significative des espaces blancs et des regroupements, ainsi qu'une organisation logique significative du code lui-même éliminent le besoin de commentaire.
C'est vraiment une négation de la prétention et de la validité de votre question, par opposition à une réponse à la question que vous aviez. Je pense toujours que c'est pertinent et peut vous aider, et je n'étais pas un con. Sinon, les -1 me domineront.
Faire apparaître le commentaire avant le code aide le lecteur à avoir un contexte pour le code qu'il est sur le point de rencontrer. Beaucoup plus humain que de leur lancer le code et d'expliquer après qu'ils sont déjà confus.
OK, je vais faire le cas "après": le code devrait toujours être la documentation principale, tandis que le commentaire (qui n'a pas de sens sémantique) est comme une explication entre parenthèses. Donc, mettre le commentaire sous le code qui a besoin d'explication laisse le code comme explication principale, et utilise simplement le commentaire pour la clarification. Par exemple,
if(date == CHRISTMAS){
//Deliver presents
val (Nice, naughty) = partition(boysAndGirls);
prepSled();
findRudolph();
putOnRedSuit();
...
}else{
//Not Christmas, build toys
monitorElves();
...
}
Si vous mettez le commentaire avant le test, le lecteur aura tendance à lire le comment comme élément principal et peut ne pas lire le code de près, ne réalisant pas qu'il a été induit en erreur:
//Check to see if it's a leap year
if(year % 4 == 0){ ... }
Les commentaires ci-dessus sont les meilleurs.
si vous devez inclure des commentaires et que votre code n'est pas explicite, je préfère ne pas être confondu par un bloc de code, puis voir "ahh, c'est ce qu'il était censé faire".
Le code peut (et devrait) être "auto-documenté", mais si vous devez lire et comprendre chaque ligne de code pour comprendre le fonctionnement d'une méthode. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.
Quand j'ai jeté un coup d'œil sur ce sujet, j'ai trouvé que la plupart des systèmes de documentation lisibles par ordinateur (Doc XML, Doxygen, Java doc etc.) s'attendent à ce que le commentaire précède le code auquel il se rapporte - c'est mieux pour rester compatible avec cette norme.
Je suis également d'accord avec le fil SO - Devrions-nous ajouter des commentaires après les blocs de code, plutôt qu'avant? ..
Je préfère aussi savoir d'avance ...
Pour emprunter certaines idées de la rédaction technique (au moins en anglais), des éléments tels que les notes et les avertissements sont généralement placés avant l'instruction ou la section à laquelle s'applique la note ou l'avertissement.
Je ne vois pas pourquoi le code ne peut pas être considéré comme une forme d'écriture technique - chaque bloc est une instruction. Comme la langue anglaise, la plupart des langages de programmation sont lus de gauche à droite, de haut en bas. Les commentaires sont des notes sur le code - ils peuvent identifier des erreurs à corriger ou des choses dont un futur développeur pourrait avoir besoin.
Suite à cette relation, il semble plus approprié de placer le commentaire au-dessus du bloc de code auquel il se réfère.
Un commentaire peut devoir aller au-dessus ou au-dessous d'un morceau de code, selon le type de commentaire: s'il donne une explication ultra brève de ce que fait le code, alors il doit précéder le code; s'il clarifie minutieusement un détail technique sur le fonctionnement du code, il doit alors suivre le code.
Heureusement, un commentaire peut aller au-dessus ou au-dessous d'un morceau de code et ne laisser aucun doute sur le morceau de code auquel il se rapporte, en utilisant correctement les lignes vides. Bien sûr, les programmeurs qui ne font pas attention à l'utilisation de lignes vierges ne sauront pas de quoi je parle; si vous êtes de ceux-là, veuillez sauter cette réponse et continuer votre vie. Mais les programmeurs qui font attention aux lignes vierges savent très bien que les lignes vides sont utilisées pour diviser le code en entités logiques. Donc, si vous voyez ce qui suit:
[blank line]
/* comment */
{ code }
[blank line]
Vous savez que le commentaire appartient au code et qu'il vous indique ce que fait le code. Attendu que si vous voyez ce qui suit:
[blank line]
{ code }
/* comment */
[blank line]
Encore une fois, vous savez très bien que le commentaire appartient à ce code, et c'est une clarification sur la façon dont le code fait ce qu'il fait.
Je convertis souvent les commentaires (les miens aussi bien qu'écrits par d'autres) en instructions de journal de niveau de trace. Cela rend généralement beaucoup plus facile à comprendre où le placer.
// Return an empty list if we failed to retrieve anything
// I convert above to:
logger.trace("Return an empty list if we failed to retrieve anything");
Un avantage supplémentaire est que lorsque la situation devient difficile, je peux activer le suivi des journaux et obtenir un journal d'exécution plus détaillé.