Lenken die Kommentare der ersten Person ab und sind unprofessionell?

63

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?

Dan Rasmussen
quelle
1
Kommentare zum Downvote? Dies ist meine erste Programmierer.SE-Frage, und ich versuche immer noch, genau herauszufinden, was eine gute P.SE-Frage zu einer guten SO-Frage macht.
DLRAS2
2
Ich habe Sie nicht abgelehnt, aber ich konnte mir vorstellen, dass ihnen die Titelfrage nicht gefiel, da die Antworten leicht kurz und gesprächig sein und einer unbegründeten Meinung zuviel gegeben werden könnten. Eine Umformulierung, die eher Ihrer letzten Frage entspricht, könnte hilfreich sein.
DKnight
56
Ich mag das Wir. Es ist freundlich und inklusiv in einer gesunden, volkstümlichen Art und Weise.
Jeremy
25
Ich denke, ich werde anfangen, alle Fehlerbehebungen zu kommentieren, an denen ich in der dritten Person arbeite, die allwissend ist und die mich im Büro populär machen sollten durch das
ewig
4
Das ist alles, was ich tun kann, um sicherzustellen, dass meine Kommentare keine blöden Tippfehler enthalten. Jetzt muss ich mir Gedanken darüber machen, ob Passivsprache verwendet werden soll oder nicht. Als nächstes muss ich sicherstellen, dass ich keine Präpositionen verändere - ich stelle mir vor, dass meine Kollegen das nicht ertragen. Und ich nehme an, ich werde niemals einen geteilten Infinitiv verwenden dürfen. Satzfragmente?
Michael Burr

Antworten:

103

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".

Whatsisname
quelle
3
+1, wenn Sie auf diese Weise schreiben, ermutigt Sie der Autor, den potenziellen Leser zu berücksichtigen, und das kann Ihnen wirklich dabei helfen, Konzepte zu erkennen, auf die möglicherweise besser eingegangen werden muss.
Justin Ohms
64
// we approve of this answer:)
Jarrod Dixon
3
+1 und eine Verstärkung: Im Gegensatz dazu werden Passiv-Sprachkonstruktionen wie "es kann die Größe geändert werden" im Allgemeinen schriftlich abgelehnt, da sie für uns schwer verständlich sind. Wenn Sie Passivsprache verwenden, zwingen Sie Ihren Leser, ein Thema für den Satz zu erfinden und sich daran zu erinnern.
msw
1
@msw: sollte das nicht "wir lehnen passive Sprachkonstruktionen wie" es kann in der Größe verändert werden "..." sein?
tdammers
2
@msw, zum Beispiel auf Russisch, sind Passivsprachkonstrukte häufiger und werden aufgrund einiger kultureller Unterschiede leichter verstanden. (Und nein, ich habe diesen Satz nicht absichtlich mit passiver Stimme geschrieben!)
P Shved
22

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.
Jonathan Khoo
quelle
4
"Wenn die Nachricht weniger ausführlich übermittelt werden kann, warum dann etwas anderes wählen?" Als jemand, der seinen Kopf gegen die Wand schlagen musste, um die schlecht dokumentierten Bibliotheken von jemandem zu implementieren - Open-Source-Bibliotheken sind dafür berüchtigt -, würde ich viel lieber zu viele Kommentare als zu wenig haben. Ich glaube, ich stimme Ihnen zu, wenn Sie gute Sätze mit korrekter Zeichensetzung meinen, die sinnvoll sind.
Jonathan Henson
3
+1 für die Nichtübernahme jeglicher Verantwortung in einer Teamumgebung. Und obwohl ich dem Versuch, ausführliche Kommentare zu vermeiden, zustimme, ist die Passivform manchmal noch schwerer zu lesen (wie von jkj hervorgehoben) und nicht weniger ausführlich, und ich ziehe es vor, eine Verschleierung zu vermeiden. =]
dlras2
2
@ Jonathan Henson: Viele Kommentare sind gut, aber nur, wenn sie viele nützliche Informationen enthalten. Wenn dieselbe Informationsmenge auf zwei gleichwertige Arten ausgedrückt werden kann, ist die kürzere besser.
Tdammers
Mein Rat ist, die Verwendung der Passivsprache zu vermeiden. Es ist schwieriger zu verstehen, insbesondere für Nicht-Muttersprachler.
Ville Laurikari
18

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".

Tesserex
quelle
Das ist auch genau mein Stil. Beide Arten, die Sie beschreiben, haben ihren Platz.
Zourtney
9
Letzteres hat auch "unser". Ich finde es interessant, dass die Leute Kommentare natürlich im Plural der ersten Person schreiben.
Reid
@Reid wow ja das war nur instinktiv, ich habe es nicht einmal bemerkt. Aber es hätte einfach "das" sagen können.
Tesserex
8

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.

Steve314
quelle
3
Ich persönlich habe nicht das Gefühl, dass "eins" datiert ist. Ja, es wird seltener verwendet, da es nicht von Zeit zu Zeit verwendet wird. Es besteht jedoch kaum die Möglichkeit, dass die Verwendung von "Eins" im Sinne eines Kommentars nicht lesbar ist oder die Benutzerfreundlichkeit auf andere Weise beeinträchtigt.
Billy ONeal
7

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)

Steven A. Lowe
quelle
3
+1 für den Vorzug Imperativ, daran hatte ich nicht gedacht. Auch ja, ich hätte das Nackte nicht benutzen sollen 1. Normalerweise bin ich ziemlich gut darin ... Überlasse es mir, eines der wenigen Male etwas zu posten, das mir im Internet durch den Kopf ging.
DLRAS2
6

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").

jkj
quelle
Ich denke sprachlich ist das nicht richtig. Der erste ist der Imperativ, er hat kein Thema. "Bitte schließe die Tür." Dies bedeutet ungefähr dasselbe wie "Bitte, können Sie die Tür schließen?" es ist eine eigenständige grammatikalische Form, keine Abkürzung. Im zweiten Beispiel könnte man genauso gut sagen "(Es hat) eine Ausnahme abgefangen. (Es wird) einen Fehlerdialog anzeigen."
Inca
3

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.

Jaybee
quelle
2
Dijkstra Achtung! Wenn nur mehr Dinge eins hätten :(
Tom Anderson
Ich denke nicht, dass das Schreiben von Kommentaren im Plural der ersten Person ein Anthropomorphismus ist. Ich denke, das impliziert: "Jetzt weisen wir den Computer an, ...", als würde der Programmierer, der den Kommentar schreibt, den Leser durch seinen Code führen.
blujay
2

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.

Bruce Ediger
quelle
Interessante Vorstellung; Wie würde man die Begriffe "X sollte mindestens 5 sein" oder "Y darf nicht größer als 23 sein" ausdrücken?
Supercat
@supercat - "Der Wert von X muss mindestens 5 betragen". Msgstr "Der Wert von Y darf 23 nicht überschreiten". Gleichheit, logisch oder arithmetisch, sollte auch nicht das "sein" -Verb verwenden. "X muss 5 enthalten" oder "X ergibt 5" oder "X hat den Wert 5" oder so. Wenn Sie auf einen besonders unklaren Kommentar stoßen, suchen Sie nach "to be" -Verbs. Ich wette, dass bei einem unklaren Kommentar nur Verben verwendet werden, die "sein" sollen. Beachten Sie auch, dass ich die Antwort oben in E-Prime geschrieben habe.
Bruce Ediger
Der zweite ist in Ordnung; das erste nicht so sehr, da -6 eine Größe von 5 oder mehr hat.
Supercat
@supercat - sehr gut. Msgstr "X muss einen vorzeichenbehafteten ganzzahligen Wert von 5 oder mehr haben". In den USA würden wir Ihren "Betrag" als "absoluten Wert" bezeichnen, was meinen Standpunkt, den Wert einer Variablen zu beschreiben, verstärkt, und nicht die Variable als Wert, die sich aus der Gleichheit ergibt.
Bruce Ediger
2

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.

user23157
quelle
11
-1 weil: es gibt keinen korrekten Weg, ich finde deine Zusammenfassung von Ich / Du / Wir ein bisschen berührungslos und verstehe den letzten Teil nicht. Nebenbei: Wenn ich in meinen Kommentaren "wir" sage, versuche ich nicht, wie ein König zu sprechen - ich spreche mit Ihnen, dem Typen, der meinen Code liest, und führe Sie Seite an Seite durch meine Gedanken.
Doppelgreener
2

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.

Thomas Owens
quelle
+1 für Doxygen und JavaDoc. Ich bin damit einverstanden, dass sich Dokumentation von Kommentaren unterscheidet (obwohl einige Kommentare Dokumentation generieren) und ich gebe mein Bestes, um diese Dokumentation einen Schritt formeller zu halten als meine Kommentare.
DLRAS2
1

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 :)

user18254
quelle
1

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 :-)

Jan Fabry
quelle
0

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.

FrustratedWithFormsDesigner
quelle
Englisch passiv hört sich selten gut an: "Eine session_id kann von SYSSession.getSessionID () bezogen werden, wenn eine benötigt wird"
jkj
0

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.
Steve Dunn
quelle
1
Sorry, aber ich bin überhaupt kein Fan dieses Stils. Zumal dieser Code einmal an einer Stelle verwendet wird und bereits das einzige Element in der Größenänderungsmethode ist. Ich würde einen kurzen, gut formulierten Kommentar der zusätzlichen Komplexität durch Refactoring vorziehen, insbesondere bei der Arbeit mit dem VB6-Debugger. Nebenbei CanThisFormBeResizedsollte es wohl sein, ThisFormCanBeResizedwenn es so benutzt wird If ThisFormCanBeResized Then.
DLRAS2
1
Das ist die Präferenz. Ich nehme eine private boolesche Methode wie function() { return this.windowState != 1 }über jeden Kommentar. +1 von mir
keppla
1
@Dan, was ist, wenn jemand anderes später vorbeikommt: Warum soll er suchen und die Logik überdenken, um festzustellen, ob ein Fenster minimiert werden kann? Sie erkennen möglicherweise nicht einmal Ihre kleine Codezeile mit einem Kommentar und fügen ihre eigenen hinzu. Jetzt gibt es 2 Stellen, die geändert werden müssen, wenn sich die Logik ändert, und 2 Stellen, an denen die Kommentare nicht mehr mit dem Code synchronisiert werden können. Warum wird eine gut benannte 1-Zeilen-Methode (die den Status nicht ändert) komplexer? Es ist die einfachste und sauberste Umgestaltung, die es gibt.
Steve Dunn
0

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.

Stephen Bailey
quelle
0

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.

Dot Net Pro UK
quelle
ResizeWindowSafelywürde bedeuten, dass es aufgerufen werden kann, wenn Sie nicht wissen, ob Sie die Größe ändern sollen oder nicht, und sich daher if (WindowState != WindowState.Minimised)selbst einschließen müssten .
DLRAS2