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

Dh

• X wurde in y geändert .
• oder
• Ändern von x zu y.

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

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.

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

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

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 .

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

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.

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

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

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.

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