Que pensez-vous des périodes / arrêts complets dans les commentaires de code? [fermé]

27

J'ai vu cela posé dans la SO Tavern , donc je poste la question ici. Je pensais que c'était une question intéressante. (Bien sûr, il n'appartient pas à SO, mais je pense que c'est OK ici.)

Ajoutez-vous des points (ou, comme l'écrit l'OP, des "points d'arrêt") dans vos commentaires de code?

Pour rester pertinent, pourquoi ?

Moshe
la source
2
Parfois je le fais et parfois je ne le fais pas. Cela dépend des commentaires et de ce qui le rend facile à lire.
Tim

Réponses:

29

Le point final est pour terminer les phrases, mais si un commentaire se compose d'une seule phrase entourée de code, le point final n'est pas nécessaire à mon avis. Parfois, je ne mets même pas en majuscule la première lettre. Un commentaire multiligne détaillé, en revanche, nécessite une ponctuation complète.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}
mojuba
la source
4
+1. Cela ressemble tellement à mon style de commentaire qu'il m'a donné un faux déjà-vu. :)
Bobby Tables
26
Non, le point final est pour marquer la fin des phrases. Peu importe que vous en ayez un ou plusieurs.
Tour
2
<joke> Ne serait-il pas préférable de vérifier le dépassement des limites int? </joke>
Dan Rosenstark
2
@Yar: une moyenne est toujours entre a et b, qui par définition sont toujours dans les limites, non? ;)
mojuba
8
Toutes mes chaînes sont terminées par null, donc un bon commentaire doit toujours se terminer par '\ 0'.
CodexArcanum
26

Oui, car les commentaires sont en anglais et un bon anglais utilise la ponctuation.

Dominique McDonnell
la source
2
Et les SMS?
Moshe
4
@Moshe, les SMS ne sont pas un bon anglais.
Dominique McDonnell
8
Anglais à peine correct, mais j'utilise toujours la ponctuation en eux. La ponctuation est là pour guider le lecteur quant à ce que l'auteur a voulu exactement - cela s'applique à n'importe quelle langue, à mon humble avis.
cjmUK
@cjmUK, Lol, oui et moi aussi. Je pensais que Moshe voulait dire que nous n'utiliserions pas la ponctuation, car je reçois régulièrement des messages comme "that wd b gr8 cu there bye" qui me font monter le mur
Dominique McDonnell
Je nu wot u ment im wiv u all da way
cjmUK
17

Ajoutez-vous des points (ou, comme l'écrit l'OP, des "points d'arrêt") dans vos commentaires de code?

Pour rester pertinent, pourquoi?

Pour la même raison, je les ajoute lors de l'écriture de texte "normal" - ils font partie de la langue écrite, et ils ne devraient pas avoir de particularité. Je les utilise également lors de la rédaction d'une phrase (une ligne) de commentaires ainsi que de paragraphes entiers.

Le code source n'est pas du texte normal, et nous utilisons donc des règles différentes pour cela. Simple ;-)

Tour
la source
Un de mes amis ne captialise jamais les mots dans les courriels ... parce que c'est sur Internet. Pour moi, c'est bien quand vous adaptez votre écriture à des limites techniques comme les SMS, mais en quoi les e-mails ou le code source sont-ils différents du texte des lettres et des livres?
LennyProgrammers
1
@ Lenny222 - Je ne sais pas ce que vous demandez ici. Les e-mails doivent être écrits comme du texte normal; comme si vous écriviez une lettre comme vous le dites. Comment ils sont réellement écrits (et les SMS, oh boy, ne me lancez pas sur les SMS :) Le code source ne se soumet pas aux mêmes règles que le texte normal, car il a ses propres règles de syntaxe.
Tour
2
Pour moi, les commentaires du code source sont destinés à être lus par des êtres humains. Pourquoi cela devrait-il faire une différence si certaines informations sont dans un document de spécification séparé ou incorporées dans un commentaire de code source?
LennyProgrammers
@ Lenny222 - Quelque chose vient de m'arriver, juste pour qu'il n'y ait pas de malentendu entre nous. Nous parlons maintenant du code source ou des commentaires qui y sont intégrés? S'il s'agit du deuxième cas, je m'excuse, car je vous ai mal compris. Dans ce cas, les mêmes règles s'appliquent que pour le texte normal (pour les commentaires). Dans le code source réel (celui qui est lu par le compilateur / interprète), je ne vois pas comment les mêmes règles pourraient suivre.
Tour
1
Oui, je pense que nous sommes d'accord sans le savoir. ;)
LennyProgrammers
9

Si vous écrivez des commentaires, on espère qu'ils seront écrits en anglais. Cela étant le cas, il faut bien ponctuer. Faire autrement serait paresseux.

vite_maintenant
la source
1
Les périodes sont pour la fin d'une phrase. Les commentaires ne sont pas nécessairement des phrases complètes.
John B. Lambe
Les commentaires, en général, devraient être des phrases. Sinon, je devrais demander pourquoi. Si vos commentaires sont si courts qu'ils ne sont pas des phrases, sont-ils peut-être évidents et donc superflus?
quick_now
5

Si j'écris une phrase complète (ou plus), alors oui. Si je ne le fais pas, alors parfois non, mais généralement toujours oui.

Je deviens aussi parfois fou et j'utilise des points d'exclamation, des points d'interrogation, etc.;)

Quant à savoir pourquoi, c'est en partie parce que je suis juste particulier comme ça et en partie parce que je trouve que la ponctuation appropriée peut ajouter beaucoup de clarté.

Adam Lear
la source
Si vous utilisez des points d'interrogation, comprenez-vous votre propre code?
Moshe
@Moshe: Ceux-ci sont généralement dans TODO quand je ne comprends pas encore complètement mon propre code.
Adam Lear
2
@Moshe - Pourquoi les commentaires ne peuvent-ils pas inclure de questions? Les questions peuvent être rhétoriques. En fait, je nous souvent? dans mes commentaires - lors de la description du code conditionnel, plutôt que d'une explication sèche de la logique, il est souvent plus clair de décrire la logique comme une question. Par exemple, "Les critères de qualification sont-ils remplis? Si non, afficher un avertissement à l'utilisateur."
cjmUK
1
En travaillant avec de grands projets et de nombreux collaborateurs, je trouve souvent que les commentaires d'interrogation sont les plus importants.
LennyProgrammers
3

Les autres réponses et leur popularité ont clairement montré que les arrêts complets sont bien appréciés dans les commentaires plus longs et peuvent probablement être évités dans les lignes simples.

Un autre point qui pourrait être pertinent est d'éviter les points d'exclamation, en particulier les multiples . Exemple:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

et

    // This code really sucks!

En revanche, les points d'interrogation sont parfois très utiles:

    // TODO: What does Crojpler.bway() actually do?
Dan Rosenstark
la source
1

Ça dépend. Si j'écris un grand paragraphe approprié expliquant ce que fait un bloc de code, je le ponctue correctement, comme tout autre élément d'écriture approprié. OTOH, quand je commente juste une seule ligne de code, alors je ne le fais pas.

Pourquoi? - Similaire à la raison pour laquelle j'écris des e-mails en utilisant une écriture appropriée, alors que je pourrais utiliser des phrases abrégées dans les messages SMS. Dans un cas, je m'assois pour écrire un bloc de texte approprié, alors je le "fais correctement" automatiquement, tandis que dans l'autre, ce n'est qu'une brève note pour faire passer un point.

De vrais exemples de mon code:

Commentaire de note rapide:

// check for vk_enter

Documentation de la méthode "appropriée":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.
Tables Bobby
la source
Développeur .NET, hein? ;-)
Moshe
@Moshe: Java en fait. Il s'agit du code d'une applet très grande et complexe, essentiellement comme une application Swing de bureau, sauf qu'elle s'exécute dans le navigateur. :)
Bobby Tables
Je pensais que MDI est un terme .NET.
Moshe
@Moshe: Non, c'est générique ( en.wikipedia.org/wiki/Multiple_document_interface ).
Bobby Tables
1

Oui, je pense que de cette façon, vous créez une bonne convention de codage et cela crée également un code lisible pour une troisième personne examinant votre code.


la source
1
Et une deuxième personne?
daviewales
0

Je capitaliserai et ponctuerai toujours correctement lors de la création de commentaires XML que je m'attends à voir dans IntelliSense et dans notre documentation générée . Ce sont des constructions beaucoup plus formelles et doivent être traitées comme telles.

Cependant, les commentaires qui viennent d'être vus dans le corps d'un bloc de code doivent être aussi clairs que possible. C'est au programmeur comment ils y parviennent.

Matt DiTrolio
la source