Lenken die Kommentare der ersten Person ab und sind unprofessionell?

Ich habe gerade festgestellt, dass ich in einem (archaischen Visual Basic 6.0) Code, den ich geschrieben habe, den folgenden Kommentar geschrieben habe:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Ich bin mir nicht sicher, warum ich unbewusst "wir" in meinen Kommentaren verwende. Ich vermute, es liegt daran, dass sich jemand vorstellt, der durch den Code geht, als würde er tatsächlich alle Befehle in jeder Zeile "ausführen", anstatt nur zuzusehen, wie sie ausgeführt werden. Mit dieser Einstellung hätte ich etwas anfangen können I can resize it, da ich derjenige bin, der es gerade "tut", oder you can resize itals ob ich mit wem auch immer in Zukunft "tue", aber da beide dieser Fälle höchstwahrscheinlich sind Zufällig benutze ich "wir", als würde ich jemanden durch meinen Code führen.

Ich kann es einfach umschreiben, it can be resizedum das Problem zu umgehen, aber es hat meine Neugier geweckt: Ist es üblich, die erste Person wie diese in Kommentaren zu verwenden, oder wird es als ablenkend und / oder unprofessionell angesehen?

Kommentare sollten geschrieben werden, damit die Menschen sie verstehen können. Wenn Menschen kommunizieren, verwenden wir normalerweise "Ich", "Wir", "Sie" usw.

Wenn jemand versucht, einen Code zu verstehen, gibt es zwei oder mehr Akteure: die Person, die ihn liest, und den ursprünglichen Autor des Codes. "Wir" zu sagen ist in Ordnung. Wenn Sie nicht "professionell" meinen, meinen Sie "roboterartig".

Ich würde vorschlagen, sich von der Verwendung von 'I' fernzuhalten, da diese automatisch die gesamte Verantwortung für den Code übernimmt. Wenn andere Leute es lesen, würde es schlecht aussehen, weil es in diesem Fall eine Teamleistung sein soll. Mir ist es gleichgültig, 'wir' zu benutzen. Es kann jedoch vorkommen, dass andere Leser nur ungenau einbezogen werden.

Meine Stimme ist immer noch kurz und prägnant. Wenn die Nachricht weniger ausführlich übermittelt werden kann, warum dann etwas anderes wählen? Zu diesem Beispiel würde ich also schreiben:

'The form is not minimized so it can be resized safely.

Ich verfolge einen von zwei Ansätzen, normalerweise alles, was besser klingt.

Wenn ich Dinge wie Anforderungen oder Rechtfertigungen erkläre, gehe ich mit "wir" vor, wie Sie es dort getan haben:

// We can't proceed unless the user has given us this information.

Wenn ich den Prozess erkläre, neige ich dazu, eine imperative (Befehls-) Stimme zu verwenden (korrigieren Sie mich, wenn dies der falsche Begriff ist):

// Get the foo from bar and make sure it follows our required format.

Letzteres kann gefährlich nahe daran sein, den Code zu wiederholen, aber es gibt Verwendungen. Es benutzt also nicht ich oder wir, sondern impliziert "Sie".

Ich denke, es ist nur eine Variation des akademischen / technischen Schreibstils, die oft unpersönlich ist. Mit der passiven Stimme, mit dem "königlichen Wir" ("Eins" ist so datiert).

Als allgemeine Regel gilt, es ist nicht-spezifische , die es trotzdem verwenden - der Kommentar für Maintainer zugute kommen, die normalerweise nicht nur für den ursprünglichen Autor.

Trotzdem benutze ich die erste Person ziemlich oft in Kommentaren, um zu erklären, warum ich bestimmte Entscheidungen getroffen habe und was ich dachte.

Kommentare sollten Ihnen sagen, warum etwas getan wird, nicht was getan wird. Wenn sich aus dem Code nicht ergibt, was gerade getan wird, korrigieren Sie den Code und fügen Sie keinen Kommentar hinzu. Die erste Person, die zweite Person usw. spielen keine Rolle, es kommt darauf an, die notwendigen Informationen zu kommunizieren.

Wenn Sie den Code erzählen müssen, bevorzugen Sie Imperative, z

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(Und bitte keine bloßen Konstanten wie "1" im Code verwenden)

Vielleicht beziehen wir uns auf die kleinen Leute im Programm, die die Magie möglich machen? :)

Englisch Passiv ist schwer zu benutzen und klingt schlecht. Leute benutzen gerne Personenformulare (ich, du, wir, eins).

Beispiel:

(Sie / wir / einer müssen / müssen) einen Delegaten verwenden, um Fenstergrößenänderungsereignisse an die Eltern zu übergeben

Ein Delegat muss verwendet werden, um Ereignisse zur Größenänderung des Fensters an das übergeordnete Element zu übergeben

Ein weiteres Beispiel (beachten Sie, dass Sie die Personenformulare in Kommentaren häufig weglassen können):

(Wir) haben eine Ausnahme erwischt. (Wir werden) einen Fehlerdialog anzeigen.

Eine Ausnahme wurde abgefangen und ein Fehlerdialog wird angezeigt.

PS. Das Ersetzen von passiv durch "Sie" ist in der englischen Sprache so verbreitet, dass es auch in andere Sprachen gelangt. Es klingt zum Beispiel auf Finnisch extrem lustig, wenn die zweite Person Singularform existiert (wie das englische "du").

Wenn Sie über die Ausführung des Programms sprechen, sind es nicht "wir", "Sie" oder "Ich". Anthropomorphismus mag so verbreitet sein, dass er nicht bemerkt werden kann, aber er ist eine gefährliche Angewohnheit (PDF Warning. Dijkstra Warning.):

Ich denke, Anthropomorphismus ist am schlimmsten. Ich habe jetzt Programme gesehen, die "versuchten, Dinge zu tun", "Dinge tun zu wollen", "Dinge für wahr zu halten", "Dinge zu wissen" usw. Seien Sie nicht so naiv zu glauben, dass dieser Sprachgebrauch harmlos ist. Es fordert den Programmierer auf, sich mit der Programmausführung zu identifizieren, und zwingt ihn fast zur Verwendung der operativen Semantik.

Ich denke nicht, dass entweder die erste Person oder das "königliche Wir" unprofessionell oder ablenkend wirken. Ich denke, wir sollten uns bemühen, englischsprachige Kommentare in E-Prime zu schreiben , der Untergruppe des Englischen, die das Verb "sein" nicht besitzt.

Wenn Sie in Kommentaren übermäßig "sein" verwenden, erhalten Sie verwirrende Aussagen wie:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Nun, vielleicht nicht alle auf einmal, aber die Ungleichheit kann wirklich zu unklaren Kommentaren führen.

Ich denke, dass das Schreiben von Anforderungen in E-Prime dazu beiträgt, diese Anforderungen klarer zu machen, da der Autor zusammen mit der Aktion einen Schauspieler angeben muss.

Der richtige Stil zum Kommentieren ist die dritte Person unpersönlich; Msgstr " Das Formular wird nicht minimiert, so dass die Größe sicher geändert werden kann ".

• Ich bin naiv
• Du bist krass.
• Wir sind zu formal (und königlich).

Jeder Satz kann auf diese Weise umformuliert werden (siehe oben) und es ist die einzige professionelle Art zu schreiben.

Es kommt auf den Kommentar an.

Normalerweise schreibe ich Kommentare in der von The Mouth of a Cow vorgeschlagenen Weise . Auf diese Weise schreibe ich auch immer dokumentationserzeugende Kommentare (Doxygen, JavaDoc).

Viele vernachlässigen jedoch häufig die Verwendung der Versionskontrolle, um festzustellen, wer Zeilen in Quelldateien geschrieben / berührt hat. Manchmal ist es angebracht, "Ich" zu sagen, besonders wenn es ziemlich einfach ist, das "Ich" der Person zuzuordnen, die den Code geschrieben hat. Wenn Sie als Einzelperson eine Entscheidung getroffen haben, empfehle ich die Verwendung von "I" (zusammen mit der Versionskontrolle), um Entscheidungen im Einklang mit dem Code zu identifizieren und zu verfolgen.

Mein guter alter Vater (mhrip) fragte: "Hast du keine wichtigeren Dinge zu erledigen?"

Ich persönlich mag das "Wir". Und ich frage mich auch, warum ich wir in Upstream-Dokumenten schreibe, nicht einmal in Code, wenn ich bedenke, dass ich der einzige Mitarbeiter in meinem Unternehmen bin.

Ich und ich sind uns jedoch einig, dass wir uns auf diese Weise weniger einsam fühlen :)

Bin ich der einzige, der "wir" schreibt und "ich und der Computer" denkt (oder "mein Team und der Computer")? "Wir" werden die von außen gestellte Anfrage bearbeiten, dh "wir" müssen die Anfrage lesen, einige Fenster öffnen, einige Berechnungen basierend auf "unseren" Geschäftsanforderungen durchführen. Dies hilft auch dabei, den Code als Teil Ihrer Seite zu sehen, nicht als Feind :-)

Für kurze Kommentare schreibe ich manchmal in der zweiten Person, als würde ich jemand anderen anweisen, fast als Nachricht an den nächsten Entwickler, den Kommentar zu lesen. Sowie

//You can get a session_id from SYSSession.getSessionID() if you need one

Längere Kommentare (wie ein langer Funktionsheader oder mehrere Zeilen der Algorithmusbeschreibung) Ich versuche, neutral zu bleiben, keine erste Person, zweite Person oder dritte Person.

Sie haben diesen Kommentar hinzugefügt, weil der Code nicht klar genug war. Ich finde im Allgemeinen, dass das Ausdrücken von Absichten durch genau definierte Methoden die Verwendung von Kommentaren vermeidet. Diese Zeile könnte beispielsweise in eine Methode mit dem Namen verschoben worden sein CanThisFormBeResized.

Eine gut benannte Methode, wie klein sie auch sein mag, schlägt einen Kommentar, da Kommentare und Code leicht nicht mehr synchron sind.

Wenn also die meisten Kommentare im Code ausgedrückt werden können, bleiben nur sehr wenige Gründe für Kommentare

• Wenn Ihr Kommentar Ihre Meinung ist, dann beginnen Sie mit "I"
• Wenn Sie der Meinung sind, dass Ihr Kommentar eine geteilte Meinung sein sollte (z. B. eine bewährte Methode), beginnen Sie mit "wir".
• Wenn sich Ihr Kommentar an einen zweifelhaften Code richtet , der von einem Verrückten geschrieben wurde, sollten Sie den Kommentar ausrangieren, ihn durchgehen und den verwirrenden Code eines Kollegen durchstoßen und ihn dann von Angesicht zu Angesicht mit ihm besprechen.

Als Faustregel würde ich vorschlagen, die erste Person zu verwenden, das heißt I,.

Warum? Nicht wegen des besitzergreifenden Charakters von Ich, sondern weil Menschen, wenn sie in einer anderen Perspektive sprechen, dazu neigen, zu viele Wörter zu verwenden oder Sätze zu komplex zu machen und sich beim Erklären der Dinge zu verlieren. Die erste Person ist in der Regel immer am einfachsten zu lesen.

Persönlich würde ich (in C #) schreiben:

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Oder etwas in diese Richtung, so dass die Kommentare nicht benötigt werden.