Wie schreibe ich Kommentare zu Commits?

Vorwort des Übersetzers

Im Laufe der Jahre der Softwareentwicklung, als ich Mitglied vieler Teams war und mit verschiedenen guten und erfahrenen Leuten zusammengearbeitet habe, habe ich oft dasselbe Problem beobachtet (und um ehrlich zu sein, ich habe es geschaffen) - ein totales Durcheinander im Repository. Jeder schrieb Kommentare zu Commits in seinem eigenen Stil (und wenn auch ständig in einem); Die Hälfte der Kommentare war nutzlos (aus der Kategorie " Dies ist eine Brücke "), die Hälfte der restlichen Hälfte wurde kaum verstanden.

Und dann, einen schönen Moment, sah ich diesen Artikel, bevor ich endlich die Übersetzung in die Hände bekam. Nur 7 einfache und kurze Regeln, und - siehe da - die Geschichte der Commits zu betrachten, war nicht nur nützlich, sondern auch angenehm. Nichts Revolutionäres, alles ist ziemlich offensichtlich, aber gut formuliert und zusammengefasst.

Ich möchte darauf hinweisen, dass dies ein Artikel von 2014 ist. Einige vom Autor erwähnte nicht sehr relevante Dinge könnten an Relevanz verlieren, aber das Wesentliche des Artikels ist überhaupt nicht.

Einführung: Warum gute Kommentare wichtig sind

Wenn Sie sich ein zufälliges Git-Repository ansehen, werden Sie höchstwahrscheinlich feststellen, dass der Commit-Verlauf eine Art Chaos aufweist. Schauen Sie sich zum Beispiel diese Perlen aus der Zeit an, als ich anfing, mich für das Spring-Repository zu engagieren:

 $ git log --oneline -5 --author cbeams - vor "Fri Mar 26 2009"

 e5f4b49 ConfigurationPostProcessorTests nach dem kurzen Entfernen in r814 erneut hinzufügen.  @ Ignorieren der Methode testCglibClassesAreLoadedJustInTimeForEnhancement (), da sich herausstellt, dass dies einer der Schuldigen an der jüngsten Build-Unterbrechung war.  Das Hacken von Classloadern verursacht subtile Downstream-Effekte und bricht nicht verwandte Tests.  Die Testmethode ist immer noch nützlich, sollte jedoch nur manuell ausgeführt werden, um sicherzustellen, dass CGLIB nicht vorzeitig in die Klasse geladen wird, und sollte nicht als Teil des automatisierten Builds ausgeführt werden.
 2db0f12 behebt zwei Build-Breaking-Probleme: + ClassMetadataReadingVisitor wurde auf Revision 794 zurückgesetzt + ConfigurationPostProcessorTests wurden entfernt, bis weitere Untersuchungen ergeben, warum Downstream-Tests fehlschlagen (z. B. die scheinbar nicht verwandten ClassPathXmlApplicationContextTests).
 147709f Optimiert die Dateien package-info.java
 22b25e0 Consolidated Util- und MutableAnnotationUtils-Klassen in vorhandene AsmUtils
 7f96f57 Polieren

Horror. Vergleichen Sie mit diesen neueren Commits im selben Repository:

 $ git log --oneline -5 --author pwebb - vor "Sat Aug 30 2014"

 5ba3db6 Fehler bei CompositePropertySourceTests behoben
 84564a0 Frühe Parsing-Logik von @PropertySource überarbeiten
 e142fd1 Fügen Sie Tests für ImportSelector-Metadaten hinzu
 887815f Aktualisieren Sie die Docbook-Abhängigkeit und generieren Sie ein Epub
 ac8326d polnische mockito verwendung

Welche Option würden Sie bevorzugen?

Die ersteren variieren in Länge und Stil, die letzteren sind prägnant und homogen.
Das erste wird von selbst erhalten, das zweite wird bewusst geschrieben.

Und obwohl der Commit-Verlauf vieler Repositorys wie die erste Option aussieht, gibt es Ausnahmen. Gute Beispiele sind der Linux-Kernel und Git selbst . Werfen Sie einen Blick auf Spring Boot oder ein anderes Repository, mit dem sich Tim Pope befasst.

Die Teilnehmer an diesen Projekten wissen, dass ein gut geschriebener Kommentar zum Commit der beste Weg ist, um den Kontext der Änderungen zu erläutern, die an anderen Entwicklern (sowie an sich selbst in der Zukunft) vorgenommen wurden. Die Unterschiede in den Revisionen zeigen, was sich geändert hat, aber nur ein Kommentar kann klar erklären, warum . Peter Hutterer hat es gut gesagt :

Das Wiederherstellen von der Codierung ist Zeitverschwendung. Wir können dies nicht vollständig vermeiden, daher sollten wir uns darauf konzentrieren, diese Kosten zu minimieren. Dafür sind Kommentare zu Commits gedacht. Daher zeigen sie, ob der Programmierer in einem Team gut arbeitet.

Wenn Sie nicht wirklich darüber nachgedacht haben, was ein erstklassiger Commit-Kommentar sein sollte, haben Sie wahrscheinlich nicht zu oft Git-Log und ähnliche Tools verwendet. Es gibt einen Teufelskreis: Da die Geschichte der Commits unstrukturiert und heterogen ist, verwenden sie sie nicht und achten nicht darauf. Und aufgrund der Tatsache, dass sie es nicht verwenden und nicht darauf achten, bleibt es unstrukturiert und heterogen.

Aber eine gut gestaltete Repository-Geschichte ist eine schöne und nützliche Sache. Die Befehle git tad , revert , rebase , log , shortlog und andere werden zum Leben erweckt . Es ist sinnvoll, sich die Commits und Pull-Anfragen anderer Leute anzusehen, und plötzlich ist die Hilfe ihrer Autoren nicht mehr erforderlich. Um zu verstehen, warum vor Monaten oder Jahren etwas [im Code] passiert ist, wird es nicht nur möglich, sondern auch praktisch.

Der langfristige Erfolg des Projekts hängt (unter anderem) davon ab, wie bequem es zu warten ist, und die Geschichte der Commits ist eines der mächtigsten Werkzeuge des Betreuers. Es lohnt sich, Zeit damit zu verbringen, zu lernen, wie man Ordnung hält. Zunächst kann dies zu Unannehmlichkeiten führen, aber dann wird es zur Gewohnheit und am Ende zu einer Quelle des Stolzes und der produktiven Arbeit für alle Teilnehmer.

In diesem Artikel wird nur die grundlegendste Komponente zur Aufrechterhaltung einer guten Geschichte angesprochen, nämlich das Schreiben eines Kommentars zu einem separaten Commit. Es gibt andere wichtige Dinge, wie das Zusammenführen von Commits, die hier nicht behandelt werden.

Die meisten Programmiersprachen haben allgemein beschriebene Konventionen, die einen bestimmten Stil [zum Schreiben von Code] bilden, wie z. B. Variablennamen, Formatierungsregeln usw., gut beschrieben. Natürlich gibt es verschiedene Versionen solcher Vereinbarungen, aber die meisten Entwickler sind der Meinung, dass die Auswahl und Befolgung einer Option viel besser ist als ein Durcheinander, wenn jeder in seinem eigenen Stil schreibt.

Der Ansatz des Teams zur Beschreibung von Commits sollte genau der gleiche sein. Damit die Repository-Story nützlich ist, muss sich das Team auf mindestens die folgenden drei Punkte einigen.

Stil. Markup-Syntax, Einrückung, Zeilenumbrüche, Grammatik, Großbuchstaben, Interpunktion. Überprüfen Sie immer Ihre Rechtschreibung und schreiben Sie so einfach wie möglich. Als Ergebnis erhalten Sie eine überraschend vollständige Geschichte der Commits, die nicht nur angenehm zu lesen ist, sondern die Sie auch regelmäßig lesen werden.

Inhalt Welche Informationen sollten (wenn überhaupt) im Hauptteil des Kommentars enthalten sein? Warum sollte es nicht da sein?

Metadaten Wie soll ich auf Aufgaben-IDs verweisen, Anforderungsnummern abrufen usw.?

Glücklicherweise gibt es bereits Vereinbarungen, einen aussagekräftigen Kommentar zu schreiben. Tatsächlich sind sie teilweise auf die Funktionsweise einiger Git-Befehle zurückzuführen. Sie müssen das Rad nicht neu erfinden. Befolgen Sie einfach die folgenden sieben Regeln - und Sie sind der Geschichte der Commits, die eines Profis würdig sind, einen Schritt näher gekommen.

Sieben Regeln für einen coolen Commit-Kommentar

Denken Sie daran: All dies wurde bereits gesagt .

1. Trennen Sie den Header mit einer leeren Zeichenfolge vom Body
2. Begrenzen Sie den Titel auf 50 Zeichen
3. Großschreibung der Überschrift
4. Setzen Sie keinen Punkt am Ende des Titels
5. Verwenden Sie den Imperativ im Titel.
6. Gehen Sie mit 72 Zeichen zur nächsten Zeile im Textkörper
7. Beantworten Sie im Körper die Fragen, was und warum und nicht wie

Zum Beispiel:

 Fassen Sie Änderungen mit maximal 50 Zeichen zusammen

 Hier erläutern Sie sie gegebenenfalls ausführlicher.  Follow-up
 Zeilenumbrüche von ca. 72 Zeichen.  In einigen Situationen
 Die erste Zeile des Kommentars wird als Titel betrachtet 
 Der Rest ist mit dem Körper.  Es ist unbedingt zu trennen, um voneinander zu trennen
 eine leere Zeichenfolge (wenn die Nachricht überhaupt einen Text enthält);
 Verschiedene Tools wie "log", "shortlog" und "rebase" werden es nicht verstehen
 Sie, wenn Header und Body nicht getrennt sind.

 Erklären Sie hier, welches Problem dieses Commit löst.  Zum Mitnehmen 
 mehr Aufmerksamkeit darauf, warum Sie diese Änderungen vorgenommen haben, nicht auf 
 genau wie du es gemacht hast (dies erklärt den Code für dich).
 Gibt es Nebenwirkungen oder andere nicht offensichtliche Auswirkungen in 
 diese Änderungen?  Wenn ja, muss dies hier erklärt werden.

 Absätze werden durch Leerzeilen getrennt.

  - Sie können Listen mit Aufzählungszeichen erstellen

  - Normalerweise ein Sternchen oder 
    Ein Strich mit einem Leerzeichen vor ihnen  Es gibt jedoch unterschiedliche Vereinbarungen

 Wenn Sie einen Bug-Tracker [oder ein Projektmanagementsystem] haben,
 Fügen Sie Aufgabenlinks am Ende des Textes folgendermaßen ein:

 Gelöst: # 123
 Siehe auch: # 456, # 789

1. Trennen Sie den Header mit einer leeren Zeichenfolge vom Body

Vom Handbuch zum Befehl git commit :

Obwohl dies nicht erforderlich ist, empfiehlt es sich, einen Kommentar zum Commit mit einer kurzen Zeile (weniger als 50 Zeichen) zu beginnen, in der die vorgenommenen Änderungen zusammengefasst sind, einer leeren Zeile und einer detaillierteren Beschreibung. Der Text vor der ersten leeren Zeile im Kommentar wird als Header des Commits betrachtet und in verschiedenen Git-Befehlen verwendet. Zum Beispiel verwandelt Git-Format-Patch (1) ein Commit in eine E-Mail. Das Team verwendet die Kopfzeile des Commits für den Betreff des Briefes und den Rest des Textes für den Textkörper des Briefes.

Erstens erfordert nicht jedes Commit einen Header und einen Body. Manchmal reicht eine Zeile aus, insbesondere wenn die Änderungen so klein sind, dass keine zusätzlichen Informationen erforderlich sind. Zum Beispiel:

  Tippfehler in der Einführung in das Benutzerhandbuch behoben 

Genug gesagt; Wenn der Benutzer wissen möchte, welche Art von Tippfehler behoben wurde, kann er die Änderungen einfach selbst mit git show oder git diff oder git log -p anzeigen .

Wenn Sie so etwas über die Befehlszeile festschreiben, ist es praktisch, die Option -m für git commit zu verwenden :

  $ git commit -m "Tippfehler in der Einführung in das Benutzerhandbuch behoben" 

Wenn das Commit jedoch eine Erklärung und Beschreibung der Situation verdient, müssen Sie diese in den Kommentar schreiben. Zum Beispiel:

 Derezz das Hauptsteuerungsprogramm

 MCP erwies sich als böse und war auf die Weltherrschaft bedacht.
 Dieses Commit wirft Trons CD in MCP (was zu seiner Auflösung führt).
 und verwandelt es wieder in ein Schachspiel.

Kommentare mit einem Textkörper sind mit der Option -m nicht so bequem zu schreiben. Es wäre besser, dafür einen Texteditor zu verwenden. Wenn Sie den Editor noch nicht für die Verwendung mit Git konfiguriert haben, lesen Sie diesen Abschnitt des Pro Git-Buches .

In jedem Fall zahlt sich die Trennung von Titel und Textkörper des Kommentars beim Anzeigen des Protokolls aus. Hier ist der vollständige Commit-Datensatz:

 $ git log
 Commit 42e769bdf4894310333942ffc5a15151222a87be
 Autor: Kevin Flynn <kevin@flynnsarcade.com>
 Datum: Fr 01 Jan 00:00:00 1982 -0200

  Derezz das Hauptsteuerungsprogramm

  MCP erwies sich als böse und war auf die Weltherrschaft bedacht.
  Dieses Commit wirft Trons CD in MCP (was zu seiner Auflösung führt).
  und verwandelt es wieder in ein Schachspiel.

Und hier ist der Befehl git log --oneline , der nur die Kopfzeile anzeigt:

 $ git log --oneline
 42e769 Derezz das Hauptsteuerungsprogramm

Oder der Git-Shortlog, den die Gruppe der Kürze halber vom Autor festlegt, zeigt nur den Titel:

 $ git shortlog
 Kevin Flynn (1):
       Derezz das Hauptsteuerungsprogramm

 Alan Bradley (1):
       Sicherheitsprogramm "Tron" einführen

 Ed Dillinger (3):
       Schachprogramm in "MCP" umbenennen
       Schachprogramm ändern
       Schachprogramm aktualisieren

 Walter Gibbs (1):
       Führen Sie das Protoype-Schachprogramm ein

Es gibt viele andere Situationen, in denen zwischen dem Header und dem Hauptteil des Commits unterschieden werden muss - und dazu müssen sie durch eine leere Zeile getrennt werden.

2. Begrenzen Sie den Titel auf 50 Zeichen

Technisch gesehen ist ein Überschreiten von 50 Zeichen möglich, wird jedoch nicht empfohlen. Diese Länge des Titels garantiert seine Lesbarkeit und lässt den Autor über den präzisesten und klarsten Wortlaut nachdenken, um zu beschreiben, was passiert.

Hinweis: Wenn es für Sie schwierig ist, die Ergebnisse der Arbeit zusammenzufassen, enthält ein Commit möglicherweise zu viele Änderungen. Bemühen Sie sich um atomare Commits (dies ist ein Thema für einen separaten Beitrag).

Die Benutzeroberfläche von GitHub unterstützt diese Konventionen eindeutig. Er wird Sie warnen, wenn Sie das Limit von 50 Zeichen überschreiten:


Schneiden Sie alle Überschriften mit mehr als 72 Zeichen ab und ersetzen Sie eine Ellipse:


Streben Sie also 50 Zeichen an, aber denken Sie daran, dass 72 eine strenge Einschränkung ist.

3. Großschreibung des Titels

Hier ist alles einfach. Großschreibung aller Überschriften.

Zum Beispiel:

• Beschleunigen Sie auf 88 Meilen pro Stunde

Stattdessen:

• Beschleunigen Sie auf 88 Meilen pro Stunde

4. Setzen Sie keinen Punkt am Ende des Titels

Es besteht keine Notwendigkeit dafür. Außerdem zählt jeder Charakter, wenn wir versuchen, 50 zu treffen.

Zum Beispiel:

• Öffnen Sie die Türen der Pod-Bucht

Stattdessen:

• Öffnen Sie die Türen der Pod-Bucht.

5. Verwenden Sie den Imperativ im Titel.

Imperative Stimmung bedeutet wörtlich: eine Form eines Verbs, das einen Willen ausdrückt (Ordnung, Bitte oder Rat). Einige Beispiele:

• Reinigen Sie Ihr Zimmer (räumen Sie das Zimmer auf)
• Mach die Tür zu
• Nimm den Müll raus

Jede der sieben Regeln, über die Sie lesen, ist in der imperativen Stimmung geschrieben ("Gehen Sie mit 72 Zeichen zur nächsten Zeile im Körper" usw.).

Diese Form mag etwas unhöflich klingen und wird daher nicht so oft verwendet [auf Englisch - ca. trans. ]. Aber es ist perfekt für den Commit-Header. Ein Grund ist die Tatsache, dass Git selbst den Imperativ verwendet, wenn es in Ihrem Namen festschreibt.
Wenn Sie beispielsweise git merge verwenden, wird standardmäßig die folgende Nachricht hinzugefügt:

 Zweig 'myfeature' zusammenführen

Und wenn Sie git revert verwenden :

 Zurück "Füge das Ding mit dem Zeug hinzu"
	
 Dadurch wird das Commit cc87791524aedd593cff5a74532befe7ab69ce9d zurückgesetzt.

Oder wenn Sie auf der Pull-Request-Oberfläche von GitHub auf die Schaltfläche "Zusammenführen" klicken:

 Führen Sie die Pull-Anforderung Nr. 123 von someuser / somebranch zusammen

Wenn Sie also Ihre eigenen Commit-Nachrichten in der imperativen Stimmung schreiben, befolgen Sie die in Git selbst festgelegten Regeln. Zum Beispiel:

• Refactor-Subsystem X zur besseren Lesbarkeit
• Aktualisieren Sie die Dokumentation zu den ersten Schritten
• Veraltete Methoden entfernen
• Release Version 1.0.0

Diese Methode mag zunächst unangenehm erscheinen. Wir sind eher daran gewöhnt, Indikative zu verwenden, die eher Fakten melden. Daher stellen sich Commit-Nachrichten häufig wie folgt heraus:

• Fehler mit Y behoben
• Verhalten von X ändern

Und manchmal beschreiben die Header einfach den Inhalt des Commits:

• Weitere Korrekturen für kaputte Sachen
• Süße neue API-Methoden

Es gibt eine einfache Regel, mit der Sie Fehler vermeiden können.

Ein richtig zusammengesetzter Commit-Header sollte den folgenden Satz vervollständigen:

• Wenn angewendet, wird dieses Commit < Commit-Header >

Zum Beispiel:

• Wenn diese Festschreibung angewendet wird, wird das Subsystem X zur besseren Lesbarkeit umgestaltet
• Wenn diese Festschreibung angewendet wird, wird die Dokumentation für die ersten Schritte aktualisiert
• Wenn diese Festschreibung angewendet wird , werden veraltete Methoden entfernt
• Wenn angewendet, wird dieses Commit Version 1.0.0 freigeben

Wenn diese Festschreibung angewendet wird, wird die Pull-Anforderung Nr. 123 vom Benutzer / Zweig zusammengeführt

Stellen Sie sicher, dass Verben in anderen, nicht zwingenden Stimmungen hier nicht funktionieren:

• Wenn angewendet, wird durch dieses Commit der Fehler mit Y behoben
• Wenn angewendet, ändert dieses Commit das Verhalten von X.
• Wenn angewendet, werden durch dieses Commit mehr Korrekturen für defekte Inhalte vorgenommen
• Wenn es angewendet wird, werden durch dieses Commit neue API-Methoden unterstützt

Denken Sie daran: Die Verwendung des Imperativs ist nur im Header des Commits wichtig. Im Hauptteil des Commits ist dies optional.

6. Gehen Sie mit 72 Zeichen zur nächsten Zeile im Textkörper

Git selbst ordnet Zeilenumbrüche nicht automatisch an. Wenn Sie den Kommentartext bearbeiten, sollten Sie sich den rechten Rand merken und die Zeilenumbrüche manuell festlegen.

Es wird empfohlen, mit 72 Zeichen in die nächste Zeile zu wechseln, damit Git insgesamt 80 Zeichen einrücken und trotzdem passen kann.

Ein guter Texteditor kann dabei helfen. Es ist ziemlich einfach, beispielsweise Vim zu konfigurieren, 72 Zeilen mit Zeilenvorschub zu versehen, um eine Nachricht in ein Commit zu schreiben. Es kam jedoch vor, dass IDEs schrecklich schlecht darin sind, intelligente Zeilenumbrüche für Nachrichten-Commits zu unterstützen (obwohl die neuesten Versionen von IntelliJ IDEA in diesem Teil endlich besser geworden sind). ( ca. per. - vielleicht ist im Moment alles viel besser ).

7. Beantworten Sie im Körper die Fragen „Was“ und „Warum“, nicht „Wie“.

Dieses Commit aus dem Bitcoin-Repository bietet eine hervorragende Erklärung dafür, was und warum sich geändert hat:

 Commit eb0b56b19017ab5c16c745e6da39c53126924ed6
 Autor: Pieter Wuille <pieter.wuille@gmail.com>
 Datum: Fr 1. August 22:57:55 2014 +0200

    Vereinfachen Sie die Ausnahmebehandlung von serialize.h

    Entfernen Sie den 'Status' und die 'Ausnahmemaske' aus dem Stream von serialize.h
    Implementierungen sowie verwandte Methoden.

    Als Ausnahme enthielt die Maske immer 'Failbit' und setstate war immer
    aufgerufen mit bits = failbit, alles was es tat war sofort ein zu erhöhen
    Ausnahme.  Entfernen Sie diese Variablen und ersetzen Sie den Setstate
    mit direkter Ausnahme werfen (was auch einige Tote entfernt
    Code).

    Infolgedessen wird good () nach einem Fehler nie erreicht (es gibt
    nur 2 Anrufe, von denen sich einer in Tests befindet) und können einfach ersetzt werden
    von! eof ().

    fail (), clear (n) und Ausnahmen () werden einfach nie aufgerufen.  Löschen
    sie.

Schauen Sie sich die Änderungen im Code an und überlegen Sie, wie viel Zeit der Autor den gegenwärtigen und zukünftigen Teilnehmern des Projekts gespart hat, und beschreiben Sie den Kontext der im Kommentar geleisteten Arbeit. Sonst wäre er wahrscheinlich für immer verloren.

In den meisten Fällen können Sie die Details der vorgenommenen Änderungen weglassen. Normalerweise spricht der Code in diesem Sinne für sich selbst (und wenn er so komplex ist, dass eine Klärung erforderlich ist, enthält er Kommentare).

Konzentrieren Sie sich in erster Linie darauf, zu erklären, warum die Änderungen vorgenommen wurden - beschreiben Sie die Situation vor der Änderung (und was daran falsch war), die Situation danach und warum Sie diese bestimmte Art der Problemlösung gewählt haben.

Vielleicht werden Sie sich in Zukunft dafür bedanken!

Tipps

Ich liebe die Kommandozeile. Vergessen über die IDE.

Es gibt viele Gründe - aufgrund der Anzahl der Git-Befehle -, die Befehlszeile maximal zu verwenden. Git ist ein wahnsinnig mächtiges Werkzeug. IDE - auch, aber jede auf ihre Weise. Ich benutze IntelliJ IDEA jeden Tag, ich musste mich oft mit anderen auseinandersetzen (zum Beispiel Eclipse), aber ich habe nie gesehen, dass die Integration von Git in die IDE in Einfachheit und Funktionen mit der Befehlszeile vergleichbar ist (sobald Sie es verstehen).

Bestimmte Funktionen der IDE für die Versionskontrolle sind einfach von unschätzbarem Wert, z. B. die automatische Ausführung von git rm beim Löschen einer Datei oder andere erforderliche git-Teile beim Umbenennen. Es ist jedoch viel schlimmer, wenn Sie versuchen, den Verlauf von Commits mithilfe der IDE festzuschreiben, zusammenzuführen, neu zu starten oder eine komplexe Analyse durchzuführen.

Wenn Sie das volle Potenzial von Git freischalten müssen, ist die Befehlszeile unübertroffen.
Denken Sie daran, ob Sie Bash, Zsh oder Powershell verwenden - es gibt Skripte zum Ausführen von Befehlen, die Sie vor der schmerzhaften Notwendigkeit bewahren, sich alle Unterbefehle und Optionen zu merken.

Lesen Sie das Pro Git Book

Das großartige Pro Git- Buch ( auch in russischer Sprache ) ist frei verfügbar. Nutzen Sie dies!