«Je», «Nous» ou Ni dans la documentation du code

41

Je me retrouve à écrire (espérons-le) des commentaires utiles dans la documentation de code (C ++) du type:

The reason we are doing this is...

La raison pour laquelle j'utilise "nous" au lieu de "je", c'est parce que je rédige beaucoup d'écrits académiques où "nous" est souvent préféré.

Alors voici la question. Existe-t-il une bonne raison de préférer l’un l’autre à l’autre dans la documentation du code:

  1. Utilisez "Nous": La raison pour laquelle nous le faisons est ...
  2. Utilisez "I": La raison pour laquelle je le fais est ...
  3. Utilisez mon nom: La raison en [my name]est que ...
  4. Voix passive: La raison pour laquelle cela a été fait est ...
  5. Ni l'un ni l'autre: faites ceci parce que ...

J'ai choisi l'option n ° 1 car j'ai l'habitude d'écrire de cette façon, mais la documentation n'est pas destinée à l'auteur, mais au lecteur. Je me demande donc si l'ajout du nom du développeur est utile ou s'il ajoute simplement une autre chose à faire. être changé en maintenant le code.

Alan Turing
la source
Je pense que c'est à la préférence personnelle. Je ne vois aucune raison pour laquelle l’un serait plus clair que l’autre en général.
ConditionRacer
6
Que diriez-vous n ° 5: "Quand dans le cadre d'événements humains ...";)
waxwing
8
"Quatre points et il y a sept secondes, nos ancêtres ont appris qu'il fallait absolument interdire l'
Philip
Fortement lié à l'anglais.SE: Pourquoi les programmeurs utilisent-ils toujours «nous» alors qu'en réalité ils signifient «moi» ou «vous»? (Ce qui était malheureusement fermé)
Izkata
2
Pourquoi ne pas dire This code was written like this because...? (Voix passive)
Alvin Wong

Réponses:

77

J'irais avec:

# 6. Déclaratif: ...

Plutôt que de dire "La raison en est que chaque Foo doit avoir un bar", dites simplement "Chaque Foo doit avoir un bar". Faites du commentaire une déclaration active de la raison, plutôt que passive. C’est généralement un meilleur style d’écriture en général, qui correspond mieux à la nature du code (qui fait quelque chose) et la the reason this was donephrase n’ajoute aucune information. Cela évite aussi exactement le problème que vous rencontrez.

Bobson
la source
Pourriez-vous expliquer un peu pourquoi vous feriez cela? Sans une explication, cette réponse ressemble davantage à une simple opinion, quelque peu en contradiction avec les directives de sauvegarde : «... l'opinion n'est pas si mauvaise, tant qu'elle repose sur autre chose que« parce que je suis un expert » , ou “parce que je l'ai dit”, ou “juste parce que”. Utilisez vos expériences spécifiques pour étayer vos opinions (voir ci-dessus) ou faites référence à des recherches que vous avez effectuées sur le Web ou ailleurs et qui apportent des preuves à l'appui de vos affirmations ... '
gnat
15
@gnat "La raison pour laquelle cela a été fait" n'ajoute rien à l'explication. Les commentaires doivent contenir juste assez de texte pour faire passer le message, sans plus. Laissez les subtilités, les préambules et tout autre texte de remplissage.
David Harkness
@gnat - En fait, je venais juste de finir d'ajouter plus quand j'ai vu votre commentaire.
Bobson
1
Je pense que mon exemple était trop simpliste, car en effet "la raison pour laquelle cela a été fait" n'ajoute rien. Mais il y a des cas où une situation délicate nécessite des explications, et dans ce cas, je trouve plus naturel d'utiliser "nous" ou "je", tout comme j'ai utilisé "je" plusieurs fois dans ce commentaire. Mais je pense que votre réponse est claire dans l’esprit: "déclaratif" suggère: utilisez le moins de mots possible pour faire passer le message clairement.
Alan Turing
7
Je lis //comme becausedans la plupart des cas.
Ilmo Euro
23

Je préfère ni l’un ni l’autre et je laisserais de côté cette phrase d’introduction pour aller droit au but. J'essaie également d'éviter de simplement dire "ceci" car cela ne laisse aucun moyen de savoir si le commentaire est synchronisé avec le code. En d'autres termes, au lieu de:

// The reason this was done is to prevent null pointer exceptions later on.

Je dirais:

// Frobnicate the widget first so foo can never be null.

Le fait que vous ajoutiez un commentaire implique que vous énoncez une raison. Vous n'avez donc pas besoin de dire de manière redondante aux personnes que vous expliquez la raison. Rendez la raison aussi précise que possible pour qu'ils sachent le plus clairement possible comment gérer ce code ultérieurement.

Karl Bielefeldt
la source
4

En C # (et dans la plupart des outils de documentation dans d'autres langues), il existe une différence entre la documentation et les commentaires en ligne. Mon opinion personnelle est que vous devriez toujours utiliser des commentaires formels, de type déclaratif, comme le suggèrent Bobson et d'autres dans la documentation d'un groupe ou d'un membre, mais dans le code, rien de mal à être moins formel. En fait, parfois, un commentaire informel est plus efficace pour expliquer pourquoi quelque chose est en train de don qu'une exposition complète en anglais formel.

Voici un exemple qui, je pense, illustre ce point.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}
pswg
la source
4
Note latérale: SanitizeDatadevrait retourner a SafeComplexObject. ;)
Jon Purdy
Je suis d'accord, mais je préfère les commentaires littéraux (plutôt que métaphoriques), en particulier s'il peut y avoir des développeurs de langages différents.
John B. Lambe
2

Une autre idée à considérer serait un test unitaire bien conçu qui montre pourquoi le code fonctionne comme il le fait au lieu de rédiger un commentaire descriptif. Cela présente quelques avantages par rapport à la rédaction de commentaires:

  1. Les commentaires ne changent pas toujours lorsque le code est modifié, ce qui peut créer une confusion par la suite.

  2. Les tests d'unités offrent au responsable une manière simple de jouer avec le code. Apprendre une nouvelle base de code peut être beaucoup plus facile si vous avez des unités individuelles que vous pouvez casser pour observer ce qui change.

Même si cette voie nécessite davantage de travail au début, les tests unitaires peuvent constituer une excellente forme de documentation.

mortalapeman
la source
1

Les bons commentaires sont difficiles à écrire et même les meilleurs commentaires sont souvent difficiles à lire et à comprendre. Si votre commentaire est suffisamment concis pour que je puisse l'absorber et soit suffisamment précis pour transmettre ce que j'ai besoin de savoir sur le code, cela ne me fait aucune différence quant aux pronoms que vous utilisez.

Je détesterais décourager quelqu'un de commenter son code parce qu'il est préoccupé par le cas, le temps et la personne de ses pronoms.

John M Gant
la source
Permettez-moi de préciser. Pour les commentaires qui feront partie de la documentation formelle, un ton plus formel est approprié, et il vaut mieux éviter les mots "moi" et "nous". Ce que j'avais en tête avec cette réponse était le commentaire explicatif occasionnel, par exemple lorsque vous avez fait quelque chose qui semblera faux au gars suivant. Dans les cas où seules les personnes travaillant dans la même base de code le verront jamais, je vous dis de faire ce que vous voulez, pour que votre message soit le plus clair possible, que ce soit I wrote the code this way because...ou non what we really need here is.... Dans ces cas, un commentaire clair est plus important qu'un style strict.
John M Gant
1

La raison pour laquelle j'utilise "nous" au lieu de "je", c'est parce que je rédige beaucoup d'écrits académiques où "nous" est souvent préféré.

C'est un mauvais style, même pour des travaux académiques, à moins que vous essayiez de cacher qui a réellement décidé ce point.

En ce qui concerne votre question spécifique: je ne laisserais pas un tel commentaire, à moins que cela commence par:

// TODO: clean this up, ...

ou à moins que cela explique quelque chose de très important, cela ne sera peut-être pas si clair dans le code. Dans ce cas, faites le commentaire le plus bref possible.

BЈовић
la source