web-dev-qa-db-fra.com

Quelles sont vos pensées sur les périodes / arrêts complets dans les commentaires du code?

J'ai vu cela m'a demandé dans la taverne SO , alors je pose la question ici. Je pensais que c'est une question intéressante. (Bien sûr, cela n'appartient pas, mais je pense que ça va ici.)

Ajoutez-vous des périodes (ou, comme l'a écrit OP, "Arrêts complètes") dans vos commentaires de code?

Pour le garder pertinent, Pourquoi ?

source-codecommentscoding-stylegrammar
28
Moshe

STOP complète consiste à mettre fin à des phrases, mais si un commentaire consiste en une seule phrase entourée d'un code, l'arrêt complet n'est pas nécessaire à mon avis. Parfois, je ne capitalise même pas la première lettre. Un commentaire multiligne détaillé, d'autre part, a besoin de 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; 
}
29
mojuba

Oui, parce que les commentaires sont en anglais et que l'anglais approprié utilise la ponctuation.

27
Dominique McDonnell

Ajoutez-vous des périodes (ou, comme l'opt OP a écrit, "Full STOPS") dans vos commentaires de code?

Pour le garder pertinent, pourquoi?

Pour la même raison, je les ajoute lorsque vous écrivez un texte "normal" - ils font partie de la langue par écrit et il ne devrait y avoir rien de spécial à leur sujet. Je les utilise de manière égale lors de la rédaction d'une phrase (une ligne) des commentaires ainsi que des paragraphes entiers.

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

17
Rook

Si vous écrivez des commentaires, on espère qu'ils seront écrits en anglais. Cela étant du cas, on devrait ponctuer correctement. Faire autrement serait paresseux.

9
quickly_now

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 vais aussi parfois faire des points d'exclamation et d'utiliser des points d'exclamation, des points d'interrogation, etc.)

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

5
Adam Lear

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

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

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

et

    // This code really sucks!

D'autre part, les points d'interrogation sont parfois utiles parfois:

    // TODO: What does Crojpler.bway() actually do?
3
Dan Rosenstark

Ça dépend. Si j'écris un grand paragraphe approprié expliquant ce qu'un bloc de code fait, je le presse correctement, comme tout autre morceau d'écriture appropriée. OTOH, quand je viens de commenter une seule ligne de code, alors je ne le fais pas.

Pourquoi? - similaire à la raison pour laquelle j'écris des courriels en utilisant une écriture appropriée, tandis que je pourrais utiliser des phrases sténographiques dans SMS messages. Dans un cas, je suis assis pour écrire un bloc de texte approprié, donc je viens automatiquement automatiquement "Faites-le correctement", tandis que dans l'autre, c'est juste une brève note pour obtenir un point à l'autre.

Exemples réels de mon code:

Note rapide Commentaire:

// check for vk_enter

Documentation 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.
1
Bobby Tables

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

1
Aditya

Je vais toujours correctement capitaliser et ponctuer lors de la création Commentaires XML que je m'attends à être vu dans IntelliSense et dans notre Documentation générée. Ce sont des constructions beaucoup plus formelles et devraient être traitées comme telles.

Les commentaires vient de voir dans le corps d'un bloc de code, cependant, devraient simplement être aussi clairs que possible. C'est au programmeur comment ils atteignent cela.

0
Matt DiTrolio