Commentaire avant ou après le code correspondant [fermé]

En supposant qu'un commentaire ne va pas (ou ne peut pas aller) sur la ligne à laquelle il s'applique, faut-il écrire le commentaire avant ou après le code?

Eh bien, là où les futurs lecteurs comprendront mieux la portée du commentaire. En d'autres termes, la plupart des programmeurs / scripteurs insèrent 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 concerne que des langues spécifiques, veuillez indiquer laquelle.

Et si vous pouvez citer une spécification acceptée ou un guide qui corrobore votre réponse, tant mieux.

Je voudrais commenter inline ou avant le code auquel le commentaire devrait s'appliquer. Le sens des commentaires consiste à comprendre le fonctionnement du code sans avoir à le lire lui-même. Il est donc beaucoup plus logique de placer les commentaires avant le code qu’il décrit.

Microsoft indique que ce serait une bonne pratique de programmation de commencer les procédures avec un petit commentaire. (Ils ne mentionnent pas les commentaires après les procédures) MSDN Le lien concerne VisualBasic, mais il s’applique à la plupart des langages de programmation.

Je préfère que les commentaires soient au-dessus du code auquel ils font référence, il est plus logique de dire à une personne qui lit le code de ce qui va arriver plutôt que d'essayer de faire référence au code précédent pour expliquer que certaines lignes de code désordonnées ont corrigé un bogue qui était délicat. alors n'y touchez pas.

Je pense que le code se lit généralement de haut en bas. À tout le moins, la mémoire musculaire me ferait associer un commentaire à la prochaine ligne de code située en dessous.

En règle générale, le commentaire doit figurer en haut de la ligne, après le même retrait que le travail. Par exemple, commentez au-dessus du corps des fonctions et un liner commente 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 pourquoi quelque chose est fait de cette manière; où comme la personne ne sait pas jusqu'à quel point il faut faire défiler pour obtenir la réponse. Si c'est sur le 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 diverses langues, je ne me souviens pas d’avoir vu un code dans une langue où un commentaire est placé sur une nouvelle ligne après le code auquel elle fait référence. Aux États-Unis, au moins, la norme de facto consiste à commenter avant le code ou sur la même ligne suivant le code. Écrire vos commentaires après que le code associé invite à un test de dépistage de drogue, une évaluation psychiatrique et / ou une date avec une pince et une lampe à souder.

La seule exception à laquelle je peux penser est un commentaire marquant la fin d'une section déjà commentée, comme ceci:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin a écrit un essai bien pensé sur les commentaires qui mérite 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 après.

Essayez de commenter uniquement là où c'est vraiment nécessaire. le code doit essayer de s'auto-documenter chaque fois que possible.

Cela étant dit, l'emplacement peut dépendre: Si vous utilisez une ligne distincte pour le commentaire, placez-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;

Contre.

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. Au cours d'un cours de génie logiciel, j'ai été initié à l'idée d'un code auto-documenté. Le code est la seule documentation correcte à 100% qui soit - les commentaires doivent être mis à jour, construits avec soin et pertinents, sinon ce sont des pièges qui peuvent être pires que l'absence 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, les commentaires sont nécessaires. Souvent, la dénomination soignée des variables, l'utilisation judicieuse des espaces et des groupes et une organisation logique significative du code en soi suppriment la nécessité du 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 que cela peut vous aider, et je n'étais pas un imbécile. Sinon, les -1 vont me dominer.

Faire apparaître le commentaire avant le code aide le lecteur à définir un contexte pour le code qu'il va rencontrer. Beaucoup plus humain que de leur jeter le code et d'expliquer après qu'ils soient déjà confus.

OK, je vais faire le cas "après": le code doit toujours être la documentation principale, alors que le commentaire (qui n'a pas de signification sémantique) ressemble à une explication entre parenthèses. Donc, placer le commentaire sous le code qui a besoin d'une explication le laisse comme explication principale et utilise simplement le commentaire à des fins de 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 va tendre à lire le commentaire comme la chose principale et ne peut pas lire le code près, sans se rendre compte qu'ils ont été induits en erreur:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Pour emprunter des idées à la rédaction technique (du moins en anglais), des notes et des avertissements sont généralement placés avant l'instruction ou la section à laquelle s'applique l'avertissement ou la mise en garde.

Je ne vois pas pourquoi le code ne peut pas être considéré comme une forme de rédaction technique - chaque bloc est une instruction. Comme en anglais, la plupart des langages de programmation sont lus de gauche à droite et 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 fait référence.

Un commentaire peut devoir être placé au-dessus ou au-dessous d'un morceau de code, selon le type de commentaire utilisé: s'il fournit une explication très brève de ce que fait le code, il doit précéder celui-ci; s'il clarifie minutieusement un détail technique sur le fonctionnement du code, il doit alors le suivre.

Heureusement, un commentaire peut aller au-dessus ou au-dessous d'un morceau de code, sans laisser de doutes sur l'élément de code auquel il se rapporte, en utilisant correctement les lignes vierges. 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à, passez cette réponse et passez à autre chose. Mais les programmeurs qui font attention aux lignes vides savent très bien que ces lignes servent à 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 dit ce que le code fait. Considérant 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 qu'il clarifie la manière dont le code agit comme il le fait.

Les commentaires ci-dessus sont les meilleurs.

si vous devez inclure des commentaires et que votre code n'est pas explicite, alors je préférerais ne pas être dérouté par un bloc de code, puis reportez-vous à la section "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 eu le vertige à ce sujet, j'ai constaté que la plupart des systèmes de documentation lisibles par ordinateur (Doc XML, Doxygen, Java Doc, etc.) s'attendent à ce que le commentaire vienne avant le code auquel il se rapporte - il est préférable de rester compatible avec cette norme.

Je suis également d'accord avec le fil de discussion SO - Devrions-nous ajouter des commentaires après les blocs de code, plutôt qu'avant? ..

Je préférerais aussi savoir d'avance ...

Je convertis souvent les commentaires (les miens ainsi que ceux écrits par d’autres) en instructions de journal de niveau de trace. Cela le rend généralement beaucoup plus facile de 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 les conditions sont difficiles, je peux activer le suivi du journal et obtenir un journal d'exécution plus détaillé.