Versionskontrollkommentare - Vergangenheit oder Gegenwart [geschlossen]

12

Was tun / empfehlen andere Benutzer für Versionskontrollkommentare - Vergangenheit oder Gegenwart?

Dh

  • X wurde in y geändert .
  • oder
  • Ändern von x zu y.
Robert W
quelle
27
Meinen Sie nicht "Versionskontrolle, die Kommentare überprüft"? Ich füge niemals Kommentare hinzu, die Änderungen im aktuellen Code dokumentieren. Es macht es unübersichtlich.
JohnFx
1
Ich bin wirklich verwirrt - wenn @JohnFx richtig ist, dann ist dies eine ganz andere Frage. Ich persönlich verstehe nicht, warum @Robert keine Kommentare im Quellcode bedeuten konnte.
Armand
Zu
Ihrer Information
Entschuldigung - nur um die Verwirrung zu beseitigen, habe ich Versionskontrollkommentare gemeint, eher Kommentare im Quellcode. Die Frage wurde aktualisiert.
Robert W

Antworten:

19

Kommentare sollten im Kontext gelesen werden, also:

Geschenk

Für Quellkommentare über einer Methode oder bevor ein bestimmtes Verhalten auftritt:

// This function does X
function doX() { ... }

Vergangenheit

Für Quellkommentare, nachdem ein bestimmtes Verhalten aufgetreten ist

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Und für Commit-Nachrichten

Funktion X geändert


Gemischtes Beispiel:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}
Armand
quelle
NB Ich halte alle Kommentare im obigen Code für überflüssig, aber sie wären nicht unbedingt ein nicht triviales Beispiel.
Armand
7
Jetzt hat sich die Frage geändert, diese Antwort ist etwas vom Thema abweichend.
Armand
22

Vergangenheit - Da sich jeder, der es in Zukunft liest, auf den Akt der Veränderung bezieht, wie er in der Vergangenheit geschehen ist.

Die Formulierung "Ändern" bedeutet, dass Sie gerade Änderungen vornehmen und der Code möglicherweise nicht vollständig ist.

Anmerkung: Persönlich habe ich Änderungskommentare nur eingefügt, wenn eine drastische Änderung stattgefunden hat.

Tim
quelle
10

Kommentare sind statische Dinge, daher sollten sie den Status des Programms so darstellen, wie er ist , und nicht so, wie er sein wird. Um Ihre spezifische Frage zu beantworten, ist es besser, Vergangenheitsform zu verwenden .

Diese Art von Kommentar ist jedoch besser für Ihr Versionskontrollsystem geeignet. Die Versionskontrolle erledigt die Änderungsverfolgung viel besser als manuelle Kommentare. Bei Versionskontrollsystemen ist es sinnvoller, die Gegenwart zu dokumentieren, da diese Kommentare zum Zeitpunkt der Übergabe der Änderung gelten. Aber beides wird funktionieren.

Ich würde wärmstens empfehlen, dass die einzigen Kommentare in Ihrem Code das sind, was erforderlich ist, um den Code selbst zu verstehen - den Zweck, die Geschäftslogik und Ausnahmefälle. Überlassen Sie die Dokumentation zu den Änderungssätzen Ihrem Versionskontrollsystem. Wenn Sie kein VCS verwenden, starten Sie jetzt. Es gibt verschiedene hochwertige VCS, die kostenlos sind (Subversion, Mercurial, Git usw.).

Berin Loritsch
quelle
3
+1, obwohl ich denke, dass Versionskontrollkommentare auch in der Vergangenheitsform sein sollten. :-)
Eric King
Es ist nicht schlecht, eine separate Changelog-Datei zu haben. Wenn Sie die Commit-Kommentare dort unter Quarantäne stellen, schadet das nicht allzu sehr, aber wenn Sie sie auf alle Dateien verteilen, ist das nur ein schmerzhaftes Geräusch.
Donal Fellows
Commit-Nachrichten können in beide Richtungen gesendet werden. Ich neige dazu, es so zu betrachten, als ob es sich um die derzeitige Klage aufgrund des damaligen Commits handelte. Letztendlich handelt es sich um einen Bereich in Englisch, in dem es wahrscheinlich in Ordnung ist, keine Haare zu spalten. Es ist nicht wie "Eats, Shoots and Leaves" en.wikipedia.org/wiki/Eats,_Shoots_%26_Leaves
Berin Loritsch
10

Ich benutze die imperative Gegenwart, also so etwas wie:

Ändere "x" in "y"

Dies wird von den Git-Entwicklern empfohlen :

  • Der Body sollte eine aussagekräftige Commit-Nachricht bereitstellen, die:
    • verwendet den Imperativ Präsens: "ändern", nicht "geändert" oder "Änderungen".

Es mag auf den ersten Blick etwas seltsam erscheinen, aber wenn Sie sich ein Commit als einen Patch vorstellen, der etwas bewirkt, ist es sinnvoller. (Dies gilt insbesondere für ein DVCS wie Git, bei dem Sie Änderungssätze von anderen Personen abrufen, die auf Ihr Repo einwirken.)

mipadi
quelle
1
Ich stimme zu, dass es auf den ersten Blick seltsam erscheint, und es als Patch anzusehen ist definitiv der richtige Weg. Eine Sache, die ich getan habe, ist, "Dieser Patch wird" in meinem Kopf zu rezitieren, bevor ich meine Commit-Nachricht vorlese. Es ist ein Wechsel von der Frage "Was habe ich in diesem Patch gemacht?" (Threading-Fehler behoben) Um sich zu fragen: "Was wird dieser Patch tun?" (Threading-Fehler behoben).
Nick Knowlson
5

Es ist nicht wirklich wichtig; Ich denke, es ist persönlicher Stil und Vorlieben. Wie beim Schreiben fast alles, sei einfach mit dir und anderen Kommentaren konsistent .

G__
quelle
2

Codekommentare sollten natürlich zu lesen sein.

Wenn Sie den Code gerade lesen , um sie sagen : „Dieser Code ist dabei X“ , dann sollten Sie den Kommentar im Präsens schreiben , da dies wahrscheinlich ist , wie jemand den Code zu dieser Zeit mit dem Lesen wird auch denken. Wenn Sie andererseits an einen bestimmten Punkt gedacht haben: "Dieser Code hat X", dann sollte es Vergangenheitsform sein. Am Ende kommt es auf die persönlichen Vorlieben an, es sei denn, Sie haben aus irgendeinem Grund Richtlinien, wie Sie Ihren Code kommentieren sollen (z. B. für ein Teamprojekt oder eine Klasse usw.).

Kenneth
quelle
1

Wenn Sie git verwenden, ist die Konvention, Präsens zu verwenden, da Commit-Nachrichten, die mit den git-Werkzeugen generiert wurden (z. B. Zusammenführen), Präsens verwenden.


quelle
1

Sie sollten die Vergangenheitsform verwenden.

Der Grund dafür ist, dass Sie die Frage beantworten, was mit diesem Commit erreicht wurde. Stellen Sie sich vor, Sie teilen Ihrem VCS mit, was Sie getan haben:

Festschreiben 123
XYZ geändert, um ABC auszuführen

Um Gegenbeispiele zu geben: Wenn Sie die Zukunftsform verwenden, hört sich das so an, als würden Sie jemanden bitten, dies zu tun:

Festschreiben 123
XYZ ändern, um ABC auszuführen

und wenn man die Gegenwart benutzt, hört man sich wie auf halbem Weg:

Bestätigen Sie 123
Ändern von XYZ, um ABC auszuführen

Garry Shutler
quelle
0

Verwenden Sie das Präsens: "Ändern Sie X in Y", fast so, als ob es sich um ein Element in einer klaren TODO-Liste handeln würde.

Vermeiden Sie im Allgemeinen wie bei einem Drehbuch Verben wie "sein" und "ist". Zum Beispiel ist es nicht "er geht", sondern "er geht".

Aber in diesem speziellen Beispiel - wenn es sich um Codekommentare und nicht um Check-in-Kommentare handelt - halte ich "X in Y ändern" für einen schrecklichen Kommentar. Es werden keine neuen Informationen hinzugefügt, und wenn sich der Code ändert, ist er möglicherweise sogar falsch. Es ist besser, wenn Sie den Code in eine Methode (oder eine Klasse) extrahieren und stattdessen diese Methode dokumentieren. Wenn es klar genug ist, ist nur ein guter Methodenname ausreichend.

Apropos, für die Dokumentation von Methoden können Sie die Zeitform verwenden, z. B .: "Wenn die angegebene Zahl negativ ist, abswird die Größe der Zahl zurückgegeben."

Macneil
quelle
0

Kommentare sind (oder sollten sein), wie alles Geschriebene, Ausdrücke von etwas, und sie sollten einfach den gleichen Regeln in natürlichen Sprachen folgen (unter Berücksichtigung von Abkürzungen und Abkürzungen, die spezifisch für die zu dokumentierende Situation oder das zu dokumentierende Artefakt sind).

Kommentare zum Präsens ( .ie "es ändert sich" oder "es ändert sich" ) weisen darauf hin, dass ein Datenelement, das vom dokumentierten Algorithmus verarbeitet wird, in irgendeiner Weise betroffen ist. Das heißt, es zeigt an, was der Code tut oder was mit den manipulierten Daten geschieht.

Kommentare in der Vergangenheitsform sollten auf eine Behauptung, Vorbedingung oder Nachbedingung von etwas hinweisen, das vor dem Punkt geschehen ist, an dem sich der Kommentar befindet. Beispielsweise:

Die Eingabe wurde bereits vor der Eingabe dieses Codeblocks validiert

oder

Am Ende dieses ausgeführten Codes wurden Daten in eine Datei geschrieben

Kommentare in der Vergangenheitsform können auch erklären, warum etwas getan wird ( diese Funktion führt X und Y aus, um ein Problem mit der alten Datenbank zu lösen. )

Kommentare in der Vergangenheitsform, die auf eine Änderung des Codes selbst hinweisen (.ie. X wurde in Y geändert ), sollten im Code nicht vorhanden sein. Sie sollten stattdessen als Revisionskommentare im Quellcode-Repository vorhanden sein.

Kommentare in der Zukunft sollten auf eine Bedingung hinweisen, die erfüllt oder angegangen werden muss, die jedoch aus X- oder Y-Gründen derzeit nicht ausgeführt wird. Beispielsweise:

Wenn wir die Datenbank endgültig migrieren, müssen wir diese Logik ändern

oder

TODO: Überprüfen Sie die Eingabe so schnell wie möglich erneut. Bei Eingaben des Typs X oder Y kann dies fehlschlagen. Möglicherweise sind umfangreiche Änderungen erforderlich, die derzeit nicht implementiert werden können.

Für die späteren TODO- Kommentartypen sollte eine andere Form der Dokumentation vorhanden sein, um sicherzustellen, dass solche Änderungen tatsächlich stattfinden. Das Letzte, was Sie wollen, sind TODOs, die in Zeit und Raum verloren gehen: P

Nehmen Sie es mit einem Körnchen Salz, aber normalerweise befolge ich diese Regeln, wenn ich meine eigenen Kommentare mache.

luis.espinal
quelle
0

Bei Kommentaren geht es darum, mit Menschen zu kommunizieren. Während also Konsistenz wichtig ist, ist es wichtig, sich nicht in Prinzipien zu verlieren, wenn die Prinzipien selbst einer guten Kommunikation im Wege stehen. Trotzdem verwende ich folgende Pseudostandards:

  • Kommentare, die ein gewünschtes Verhalten beschreiben, haben die Form eines Imperativsatzes in der Gegenwart.

    // Calculate the width of the curve at x height.
    
  • Verwenden Sie eine Reihe von All-Caps-Schlüsselwörtern, um allgemeine Themen in der Codierung zu beschreiben (und die Suche zu vereinfachen):

    // NOTE: <This code was written this way for a reason.>
    // TODO: <This code is incomplete. Finish it.>
    // HACK: <This code was written this way for a reason that you won't like.>
    // FIXME: <This code has a known flaw. Fix it.>
    
Kojiro
quelle