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


34

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.


3
Considère ce qui se passe quand tu le mets après. Le programmeur a lu le code. Dites-vous WTF que ça va ??? Voir le commentaire. Lisez le code à nouveau. Parfois le comprendre ou abandonner. Alors soyez gentil et évitez les parties 1 et 2 en les mettant en haut.
deadalnix

@deadalnix, merci, cela semble être l'essentiel de la réponse de Dipan Mehta également. (Merci également à tous les répondants jusqu'à présent et +1 à chacun.)
msh210

Réponses:


22

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.


1
Checkmark, car c’est la seule réponse (à ce jour) qui répond clairement à la question, qui ne visait pas une préférence personnelle, mais une procédure standard, en ce sens qu’elle cite MSDN.
msh210

1
@ msh210: Vous préférez donc une préférence de Microsoft aux préférences personnelles d'autres bons programmeurs? MAIS vous savez comment Microsoft a obtenu une erreur dans la notation hongroise en tant que norme? Oui? Le faites vous? Ne faites confiance qu'au bon sens, ne courez pas toujours avec la horde et ne suivez pas le plus gros taureau.
Falcon

2
@ Falcon, je n'ai jamais entendu parler de notation hongroise et je suppose que la préférence de MSDN était au moins le résultat de la participation de nombreux employés de MS; les réponses ici, en revanche, sont écrites individuellement.
msh210

43

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.


9

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.


7

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.


6

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.


4

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


Relisez la question: elle spécifie qu'il s'agit d'un commentaire sur une ligne séparée.
msh210

2
@ msh210 C'est une réponse parfaite. "écrire des commentaires avant". Il est encore plus détaillé et donne une raison possible pour laquelle vous pourriez penser qu'ils sont après "Sauf quand ils sont courts et au bout de la ligne."
rds

3

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.


10
Un code auto-documenté peut répondre aux questions "quoi" et "comment", mais le code, aussi bien écrit soit-il, peut rarement répondre à la question "Pourquoi?". S'il existe un document complet sur les exigences, vous pouvez parfois y trouver la réponse. Autrement, les commentaires sont souvent tout ce dont vous avez besoin pour expliquer pourquoi le code doit faire ce qu'il fait.
Ed Staub

1
Je ne suis pas d'accord Comme @EdStaub le dit, les commentaires répondent à une question différente, à un niveau différent. De plus, le code n'est pas nécessairement open-source. Et même quand c'est le cas, je ne veux pas lire un code source du framework pour savoir comment l'utiliser.
rds

4
Vous n'avez évidemment jamais traité de matériel (ni d'interface avec des logiciels mal écrits). J'ai récemment fini d'écrire un cours spécialisé pour parler à un contrôleur de moteur plutôt obscur (et grincheux ). Il a toutes sortes d'étranges exigences en matière d'interfaçage. Sauf à avoir littéralement une fonction par ligne, il n’ya aucun moyen de rendre le code compréhensible sans commentaire.
Nom

3
@ Brian, les questions "Pourquoi" sont souvent très détaillées - par exemple, contourner les bogues dans une API et / ou expliquer que quelque chose qui semble faux est en fait correct. Ce ne sont que quelques exemples. Je ne ferais pas des commentaires être un document complet d'exigences. Mais je n’essaierai pas non plus d’expliquer la logique de chaque détail de mise en œuvre dans une spécification d’exigences (ou même une spécification de conception).
Ed Staub

1
@codesparkle - Je conviens que les commentaires utilisés comme excuse pour éviter le refactoring sont généralement mauvais. Cependant, cela ne signifie pas que tous les commentaires sont mauvais, mais simplement que les commentaires ainsi abusés le sont. En réalité, il existe un certain nombre de situations dans lesquelles les commentaires sont vraiment la meilleure option pour clarifier les exigences de codage étranges.
Nom

2

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.


2

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){ ... }  

5
Vos deux blocs de code ont des commentaires avant le code qu'ils commentent.
msh210

vos propres commentaires ont annulé votre "cas après" hehe :) calin et +1 pour en faire un exemple sur le thème de Noël
Ahmed Masud

1
@ msh210 Je vois mes commentaires dans le premier exemple comme commentant le test if (noël), et non comme "concernant" les fonctions suivantes (c'est-à-dire qu'ils disent "qu'est-ce que cela signifie que nous sommes ici?") un bloc de code, mais je n'ai jamais vu de code qui avait ... code (); code(); / * commentaire expliquant le bloc précédent * /} et ne prenant pas la question de cette façon
Larry OBrien

1

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.


1

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.


Comme je le dis toujours: votre vote négatif sans explication ne m'aide pas à devenir une meilleure personne. Je t'aime aussi!
Mike Nakis

1

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 ...


1

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é.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.