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

41

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.

Alan Turing
quelle
Ich denke, es liegt an den persönlichen Vorlieben. Ich sehe keinen Grund, warum einer klarer sein würde als der andere im Allgemeinen.
ConditionRacer
6
Wie wäre es mit # 5: "Wenn im Laufe der menschlichen Ereignisse ...";)
Seidenschwanz
8
"Vor vier Punkten und sieben Sekunden haben unsere Vorfahren gelernt, dass das Foo gesperrt werden muss, damit unsere Streitkräfte nicht mit NULL besiegt werden"
Philip
Stark verwandt mit Englisch.SE: Warum benutzen Programmierer immer 'wir', wenn sie wirklich 'ich' oder 'Sie' bedeuten? (Das war leider geschlossen)
Izkata
2
Warum sagst du nicht This code was written like this because...? (Passive Stimme)
Alvin Wong

Antworten:

77

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.

Bobson
quelle
Würde es Ihnen etwas ausmachen, etwas näher darauf einzugehen, warum Sie das tun sollten? Ohne eine Erklärung sieht diese Antwort eher nach einer nackten Meinung aus, die im Widerspruch zu den Richtlinien steht : „... Meinung ist nicht alles schlecht, solange sie sich auf etwas anderes als„ weil ich ein Experte bin “stützt. oder "weil ich es gesagt habe" oder "nur weil". Verwenden Sie Ihre spezifischen Erfahrungen Ihre Meinung zu sichern, wie oben beschrieben, oder zeigen Sie auf einige der Forschung Sie im Web gemacht haben oder an anderer Stelle , die Beweise Ihre Ansprüche zu unterstützen , bietet ...‘
gnat
15
@gnat "Der Grund, warum dies getan wurde" fügt der Erklärung nichts hinzu. Kommentare sollten gerade genug Text enthalten, um den Punkt zu vermitteln, und nicht mehr. Lassen Sie die Feinheiten, Präambeln und anderen Fülltext weg.
David Harkness
@gnat - Ich habe gerade mehr hinzugefügt, als ich Ihren Kommentar gesehen habe.
Bobson
1
Ich denke, mein Beispiel war zu simpel, weil "der Grund, warum dies getan wurde" tatsächlich nichts hinzufügt. Es gibt jedoch Fälle, in denen eine schwierige Situation eine Erklärung erfordert, und in diesem Fall ist es für mich natürlicher, "wir" oder "ich" zu verwenden, so wie ich "ich" in diesem Kommentar mehrmals verwendet habe. Aber ich denke, Ihre Antwort ist im Geiste klar: "deklarativ" schlägt vor: Verwenden Sie die geringste Menge an Wörtern, die den Punkt klar vermitteln.
Alan Turing
7
Ich lese //wie becausein den meisten Fällen.
Ilmo Euro
23

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.

Karl Bielefeldt
quelle
4

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);
    ...
}
pswg
quelle
4
Randnotiz: SanitizeDatasollte a zurückgeben SafeComplexObject. ;)
Jon Purdy
Ich stimme zu, aber ich bevorzuge wörtliche (anstatt metaphorische) Kommentare, insbesondere wenn es Entwickler mit unterschiedlichem Sprachhintergrund gibt.
John B. Lambe
2

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.

Mortalapeman
quelle
1

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.

John M Gant
quelle
Lassen Sie mich klarstellen: Für Kommentare, die Teil der formellen Dokumentation werden, ist ein formellerer Ton angebracht, und "ich" und "wir" sollten vermieden werden. Was ich mit dieser Antwort im Sinn hatte, war der gelegentliche erklärende Kommentar, zum Beispiel, wenn Sie etwas getan haben, das für den nächsten Kerl falsch aussieht. In den Fällen, in denen nur Leute, die in derselben Codebasis arbeiten, es jemals sehen werden, sage ich, tue, was auch immer deine Bedeutung am klarsten wiedergibt, auch wenn es I wrote the code this way because...oder ist what we really need here is.... In diesen Fällen ist ein klarer Kommentar wichtiger als ein strenger Stil.
John M Gant
1

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.

BЈовић
quelle