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

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.

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.

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.

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

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.

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.

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.