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

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 ?

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; 
}

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

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 ;-)

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.

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

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?

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

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.

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.