"Ich", "Wir" oder Weder in der Codedokumentation

Ich finde mich (hoffentlich) hilfreiche Kommentare in Code (C ++) Dokumentation des Typs schreiben:

The reason we are doing this is...

Der Grund, warum ich "wir" anstelle von "ich" benutze, ist, dass ich viel akademisch schreibe, wobei "wir" oft bevorzugt werden.

Also hier ist die Frage. Gibt es einen guten Grund, Code gegenüber dem anderen zu bevorzugen:

1. Verwenden Sie "Wir": Der Grund, warum wir dies tun, ist ...
2. Verwenden Sie "I": Der Grund, warum ich das tue, ist ...
3. Benutze meinen Namen: Der Grund [my name]dafür ist ...
4. Passive Stimme: Der Grund, warum dies getan wurde, ist ...
5. Weder: Tun Sie dies, weil ...

Ich wähle # 1, weil ich es gewohnt bin, auf diese Weise zu schreiben, aber die Dokumentation ist nicht für den Schreiber, sondern für den Leser bestimmt. Daher frage ich mich, ob das Hinzufügen des Entwicklernamens hilfreich ist oder ob dies nur eine weitere notwendige Sache ist bei der Pflege des Codes geändert werden.

Ich würde gehen mit:

# 6. Deklarativ: ...

Anstatt zu sagen "Der Grund dafür ist, dass jeder Foo eine Bar haben muss", sagen Sie einfach "Jeder Foo muss eine Bar haben". Machen Sie den Kommentar eher zu einer aktiven als zu einer passiven Begründung. Es ist im Allgemeinen insgesamt ein besserer Schreibstil, passt besser zur Art des Codes (der etwas bewirkt ), und der the reason this was doneAusdruck fügt keinerlei Informationen hinzu. Es wird auch genau das Problem vermieden, auf das Sie stoßen.

Ich bevorzuge beides nicht und würde diesen einleitenden Satz eigentlich ganz weglassen und einfach auf den Punkt kommen. Ich versuche auch zu vermeiden, nur "dies" zu sagen, weil es keine Möglichkeit gibt zu sagen, ob der Kommentar mit dem Code synchron ist. Mit anderen Worten, anstelle von:

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

Ich würde sagen:

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

Die Tatsache, dass Sie überhaupt einen Kommentar hinzufügen, impliziert, dass Sie einen Grund angeben, sodass Sie den Leuten nicht überflüssig mitteilen müssen, warum Sie den Grund erklären. Machen Sie einfach den Grund so spezifisch wie möglich, damit sie so klar wie möglich wissen, wie dieser Code später gepflegt wird.

In C # (und in den meisten Dokumentationstools in anderen Sprachen) besteht ein Unterschied zwischen Dokumentation und Inline-Kommentaren. Meine persönliche Meinung ist, dass Sie immer formelle, deklarative Kommentare verwenden sollten, wie Bobson und andere in der Dokumentation einer Klasse oder eines Mitglieds vorschlagen, aber innerhalb des Codes gibt es nichts auszusetzen, wenn Sie weniger formal sind. In der Tat ist manchmal ein informelles Kommentar mehr wirksam zu erklären , warum etwas don wird als eine vollständige Exposition in der formalen Englisch.

Hier ist ein Beispiel, das meiner Meinung nach den Punkt veranschaulicht.

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

Eine weitere in Betracht zu ziehende Idee wäre ein gut ausgearbeiteter Komponententest, der zeigt, warum der Code so funktioniert, wie er funktioniert, anstatt einen beschreibenden Kommentar zu verfassen. Dies hat ein paar Vorteile gegenüber dem Schreiben von Kommentaren:

1. Kommentare ändern sich nicht immer, wenn der Code geändert wird, was später zu Verwirrung führen kann.

2. Unit-Tests geben dem Betreuer eine einfache Möglichkeit, mit dem Code zu spielen. Das Erlernen einer neuen Codebasis kann viel einfacher sein, wenn Sie einzelne Einheiten haben, die Sie unterbrechen können, um die Änderungen zu beobachten.

Auch wenn dieser Weg im Vorfeld mehr Arbeit erfordert, können Unit-Tests eine hervorragende Form der Dokumentation sein.

Gute Kommentare sind schwer zu schreiben, und selbst die besten Kommentare sind oft schwer zu lesen und zu verstehen. Wenn Ihr Kommentar so präzise ist, dass ich ihn aufnehmen kann und genau genug, um zu vermitteln, was ich über den Code wissen muss, spielt es für mich keine Rolle, welche Pronomen Sie verwenden.

Ich würde es hassen, jemanden davon abzuhalten, seinen Code zu kommentieren, weil er sich Sorgen über den Fall, die Zeitform und die Person seiner Pronomen macht.

Der Grund, warum ich "wir" anstelle von "ich" benutze, ist, dass ich viel akademisch schreibe, wobei "wir" oft bevorzugt werden.

Es ist ein schlechter Stil, auch für wissenschaftliche Arbeiten, es sei denn, Sie versuchen zu verbergen, wer genau diesen Punkt festgelegt hat.

Was Ihre spezielle Frage betrifft: Ich würde einen solchen Kommentar nicht hinterlassen, es sei denn, er beginnt mit:

// TODO: clean this up, ...

oder es sei denn, es erklärt etwas sehr Wichtiges, was aus dem Code möglicherweise nicht so klar hervorgeht. Machen Sie in diesem Fall den Kommentar so kurz wie möglich.