Wie kann ich meine Kollegen davon überzeugen, Kommentare zu Quellcode-Commits hinzuzufügen?

Ich weiß, dass Subversion (das, was wir bei der Arbeit verwenden) so konfiguriert werden kann, dass Kommentare zu Commits erforderlich sind, aber ich bin nicht in der Lage, dies einfach einzuschalten. Ich weiß, dass mein Grund für das Kommentieren meiner Commits darin besteht, dass es nützlich ist, wenn auch nur als Memory-Jogger, den Grund für das Commit schnell zu verstehen. Dies scheint jedoch nicht genug zu sein, um die beiden Antworten zu bekämpfen, die ich immer bekomme:

1. Es dauert zu lange und ich möchte nur meine Änderungen in das Repo übernehmen.
2. Es ist einfach genug, nur die Unterschiede zu betrachten.

Ich zeige ihnen sogar, welchen Wert es hat, einfach eine JIRA-Issue-ID einzugeben und wie sie automatisch mit dem Issue verknüpft wird, aber immer noch keine Würfel dabei.

Am schlimmsten ist, dass die Person, die den Anruf tätigen kann , im selben Lager ist: Sie möchte sich nicht darum kümmern und kann gut Unterschiede betrachten.

Ich weiß, es ist das Richtige, aber wie kann ich sie dazu bringen, das Licht zu sehen? Auch wenn ich meine Kollegen nicht überzeugen kann, wie kann ich das Management davon überzeugen, dass es das Richtige für das Unternehmen ist?

Fokus auf "Warum". Es ist alles sehr gut, wenn man sich die Unterschiede ansieht und sieht, dass jemand den logischen Ablauf eines Codeabschnitts oder dergleichen geändert hat, aber warum hat er ihn geändert? Das Warum steht normalerweise im zugehörigen Ticket (JIRA für Sie).

Sie fragen sich vielleicht, warum das "Warum" wichtig ist, aber in zwei Jahren, wenn Sie einen Fehler entdeckt haben, der die Auswirkungen dieser Änderung nach sich zieht, ist es unglaublich wichtig, dass Sie nicht nur den neuen Fehler beheben, sondern auch sicherstellen, dass er behoben wurde Sie lassen den alten Bug nicht wieder auftauchen.

Es gibt auch den Prüfungsgrund. Verbindliche Commits und Ticket-IDs machen es wirklich einfach, "OK" zu sagen. Wir haben Version 2 herausgebracht. Dies behebt Fehler 23, 25, 26 und 27, aber es gibt keine Commits gegen Fehler 24, so dass es immer noch aussteht.

Lassen Sie sie die Zusammenschlüsse vornehmen und kümmern Sie sich um die Unterstützung. Vielleicht sind Sie auch hier nicht in der Lage, dies zu tun, aber wenn Sie derjenige sind, der ein Problem von einem früheren Commit löst, senden Sie es höflich über den Zaun und sagen Sie. Ich kann nicht sagen, was Sie getan haben, da es keine Festschreibungskommentare gibt. Sie haben diese Änderungen vorgenommen, um es herauszufinden.

Auch zum Zusammenführen von Filialen. Ich bin mir nicht sicher, ob das auf dich zutrifft oder nicht, aber in diesem Bereich fand ich Kommentare hilfreich.

Wieder nicht in Ihrem Boot, aber als ich ein Software-Team leitete, sagte ich ihnen, wenn sie gute Commit-Kommentare machten, würde ich diese in Form eines wöchentlichen Statusberichts verwenden. Erhielt danach exzellente Commits und es war für mich einfacher, den Überblick zu behalten, was als Manager vor sich ging.

Wir benötigen Check-in-Kommentare aus dem gleichen Grund, aus dem wir Zeilenumbrüche und Abstände in unserem Code benötigen. Um die Suche zu vereinfachen, sollten Sie das Lesen und Verstehen verstehen.

Manchmal muss man Unterschiede vergleichen, aber oft nicht. Es ist reine Zeitverschwendung, Entwickler zum Vergleichen zu zwingen, wenn sie nur 2-3 Sätze lesen müssen. Ich frage mich, warum sie den Wert der Entwicklerzeit nicht sehen.

• Ein gutes Beispiel geben. Machen Sie Ihre eigenen Commit-Nachrichten zu einem leuchtenden Beispiel für Nützlichkeit. Geben Sie Verweise auf alle anderen Systeme an, die Ihr Team zum Verwalten von Storys und Fehlern verwendet. Geben Sie eine kurze Erklärung ab, in der die Änderung zusammengefasst wird, und erklären Sie gut, warum die Änderung erforderlich ist, und nicht in jedem Beitrag etwas anderes.
• Wenn das Fehlen einer anständigen Festschreibungsnachricht zusätzliche Arbeit verursacht, stellen Sie eine Frage an den Absender. Sei beharrlich dabei (aber kein Idiot).
• Wenn Ihre Rolle nicht überschritten wird, schreiben Sie ein Skript, das mit den Festschreibungsnachrichten ein tägliches Änderungsprotokoll sendet. Dies verleiht Ihrem Argument Glaubwürdigkeit, dass nützliche Nachrichten einen Vorteil haben, der über das Durchsuchen von Revisionen hinausgeht. Dies kann auch dazu beitragen, das Management auf Ihre Seite zu bringen, da sie Tag für Tag sehen, was passiert.
• Identifizieren Sie Ihre Verbündeten. Hoffentlich gibt es mindestens eine andere Person, die mit Ihnen einverstanden ist (vielleicht indem sie stillschweigend nicht widerspricht). Finden Sie diese Person oder diese Leute und überzeugen Sie sie weiter, damit Sie nicht allein stehen.
• Wenn sich die Gelegenheit bietet, zu erwähnen, wie viel Zeit Sie mit anständigen Commit-Nachrichten gespart haben (oder schlechte Nachrichten Sie Zeit gekostet haben), nutzen Sie diese Gelegenheit.

Hab keine Angst, das quietschende Rad zu sein. Der Kampf gegen die schlechten Gewohnheiten anderer ist oft ein Zermürbungskrieg.

Dies muss eine der bizarrsten Fragen sein, die ich gehört habe. Die Leute verbringen Stunden oder sogar Tage damit, etwas zu reparieren, und zusätzliche 2 Sekunden, um eine Commit-Nachricht einzugeben, sind zu lang ?! Ich muss sagen, dass ich mir Sorgen machen würde, mit so kurzsichtigen Leuten zu arbeiten. Sie nutzen ihre Werkzeuge offensichtlich nicht einmal, um ihr volles Potenzial auszuschöpfen.

Hier ist ein Beispiel aus einer Codeüberprüfung, an der ich letzte Woche beteiligt war. Unsere Versionskontrollsoftware speichert den Verlauf über Zusammenführungen hinweg nicht. Bei älteren Änderungen müssen Sie daher den genauen Zweig ermitteln, in dem er erstellt wurde. Andernfalls wird in der Festschreibungsmeldung nur "Aus Zweig Y zusammengeführt" angezeigt. Zweig Y könnte "aus Zweig Z zusammengeführt" anzeigen, und ein Zweig, der einige Verschachtelungsebenen tiefer liegt, enthält tatsächlich die eigentliche Festschreibungsnachricht.

Ein neuer Mitarbeiter wusste nicht, wie er den Verlauf korrekt aufspüren sollte, was bedeutet, dass er im Wesentlichen nur mit den Unterschieden arbeitete. Er sah einen auskommentierten Code im Zusammenhang mit dem Fehler, den er aufspürte. Als er den Code auskommentierte, verschwand sein Fehler. Er nahm an, dass jemand den Code während des Debuggens auskommentiert und ihn fälschlicherweise eingecheckt hatte.

Während der Codeüberprüfung fühlte sich das für einige von uns nicht richtig an. Deshalb habe ich die eigentliche Commit-Nachricht aufgespürt und festgestellt, dass es einen gültigen Grund gibt, diesen Code vor einem Jahr zu entfernen. Der neue Mitarbeiter konnte seinen Code korrigieren, um den neu entdeckten Fehler zu beheben, ohne den alten erneut einzuführen.

Es gibt bessere Möglichkeiten, um die Einführung solcher Regressionen zu vermeiden, wie gründliche Komponententests, aber irgendwie sehe ich keine Leute, die sich nicht mit einer 2-Sekunden-Commit-Meldung beschäftigen, die Zeit für Komponententests verschwendet.

Ich hatte genau das gleiche Problem, also habe ich Subversion einen Pre-Commit- Hook hinzugefügt, damit keine Commits akzeptiert werden, die nicht mit der User Story-Nummer beginnen (einige grundlegende Musterübereinstimmungen für ein erwartetes Format).

Nichts hindert sie daran, 000-0000 einzugeben, aber sobald nur ein störender Idiot eine Zahl erfunden hat, hat er eine vollkommen akzeptable Zahl.

Ich habe dies getan, nachdem ich tagelang versucht hatte herauszufinden, in welche Builds eine Reihe von User Stories eingeflossen sind. Ja, es ging darum, einen Prozessfehler zu beheben, aber es sind immer noch unglaublich wertvolle Informationen zu verfolgen.

Gute Festschreibungskommentare sind wie jede gute Dokumentation, ein Cache für Ihr langsames und nicht mehr funktionierendes Gehirn oder ein Cache für das Ergebnis einer längeren Debug- / Problemanalyse / -untersuchung.

ZB wenn Sie Zeit damit verbringen, etwas herauszufinden, wie etwa das Debuggen, Analysieren von Protokollen oder was auch immer, sind Ihre Ergebnisse und Erkenntnisse wertvoll. Natürlich können die meisten Aufgaben wiederholt werden, aber es kann einige Zeit dauern. Sie sollten also immer Ihre Ergebnisse dokumentieren.

Trotzdem braucht Dokumentation Zeit und manchmal wird es als nicht notwendig empfunden, wie "wir mussten dies nur einmal tun, also warum es aufschreiben". Das ist in Ordnung, aber sobald Sie dasselbe ein zweites Mal machen, weil Sie die Ergebnisse beim ersten Mal nicht dokumentiert haben, ist es natürlich klug, die Ergebnisse zu dokumentieren.

Wenn Ihre Kollegen der Meinung sind, dass es zu aufwendig ist, Commit-Kommentare hinzuzufügen, z. B. zumindest auf den von ihnen gelösten Jira-Fall / das von ihnen gelöste Ticket zu verweisen, sind sie möglicherweise durch den Druck motiviert, ständig auf Fragen zum jeweiligen Grund zu antworten Änderungsset.

Meiner Meinung nach sollte die Dokumentation als Funktion der angeforderten Informationen erstellt werden. Mail-Korrespondenz ist beispielsweise ein ziemlich gutes Dokumentationssystem. Fragen erhalten Antworten, die später abgerufen werden können. So funktionieren Mailinglisten und Foren in der Praxis als Wissensdatenbanken.

Leider werden E-Mails an meinem Arbeitsplatz nach 3 Monaten automatisch gelöscht, sodass dies in der Praxis nicht immer funktioniert.

Bitte um Vergebung, nicht um Erlaubnis.

Während ich hart war, habe ich genau das getan. Ich hatte eine 50/50-Spaltung zwischen Unterstützern und Gegnern, von denen die meisten auf dem gleichen Niveau waren wie ich in der Gruppe. Die Argumente waren "Ich kann nicht gestört werden" und "Was ist der Sinn?". (Beides zeigt Apathie und Faulheit an, keine echten Bedenken).

Ich habe einen Pre-Commit-Haken hinzugefügt, der einfach die Länge des Strings maß und eine leicht humorvolle Nachricht abgab, bevor er abgelehnt wurde. Ich schrieb meinen Namen in die Nachricht, damit die Verantwortung für "diese Empörung" klar war. Natürlich könnte "die Opposition" es leicht entfernen, aber das Eingraben in die Skripte würde mehr Aufwand bedeuten als das Hinzufügen eines weiteren Kommentars!

Seit einer Woche habe ich Nachrichten wie * * (expletive gelöscht) oder kjhfkwhkfjhw hinzugefügt bekommen. Danach erschienen grundlegende Meldungen.

Nach einem Jahr geben die Skeptiker zu, wie kurzsichtig sie waren. Ich hätte nie einen Konsens erzielen können, aber ich habe sicherlich Vergebung und vielleicht auch Glaubwürdigkeit erhalten. Es funktioniert, die Leute benutzen es.

Wenn Sie sympathischer sein möchten (oder das Gefühl haben, in Schwierigkeiten zu geraten), fragen Sie nach der Erlaubnis, einen Commit-Hook für einen Testzeitraum hinzuzufügen. Sagen Sie, wenn die Leute es in 2 Wochen oder 4 Wochen nicht mögen, werden Sie es herausnehmen. Die Chancen stehen gut, dass sie das Interesse verlieren ... oder wachsen, um es zu mögen.

Normalerweise überzeuge ich Leute durch:

• dialektik mit guten gründen
• mit gutem Beispiel voran
• Attrition

Wenn ich wollte, dass unser Team etwas Schlimmes tut, würde ich so lange auf die Nerven gehen, bis ich mich durchgesetzt habe. Ich versuche in diesen Zeiten zu belästigen, in denen ich darauf hinweisen kann, dass wir Zeit / Geld gespart hätten, wenn wir bereits X gemacht hätten.

Weitere gute Gründe für Commit-Kommentare:

• ChangeLog wird automatisch aus den Kommentaren generiert.
• Audit-Trail für Fehlerkorrekturen und Funktionserweiterungen. Dies ist sowohl innerhalb als auch außerhalb des Teams nützlich.
• Machen Sie Commit-Mails nützlicher.
• Halte mich davon ab, Entwickler zu fragen, was Commit X macht (nach fast jedem Commit).

• Überprüfen Sie Ihre SVN-Protokolle auf etwas Unbekanntes, das vor 6 Monaten erstellt wurde.
• Stellen Sie einige Fragen zu dieser Sache, ohne zu sagen, wann sie fertig ist
• ???
• Profitieren

Wie Sie sie machen wollen gute Kommentare hinzufügen?

Aus einer Erfahrung mit einem Kollegen, die ich gerade hatte. Am Ende eines Projekts mussten wir eine Zusammenfassung aller Änderungen schreiben, die während des Projekts vorgenommen wurden. Nachdem mein Kollege keine guten Festschreibungsnotizen gemacht hatte, fand er diese Aufgabe ziemlich zeitaufwendig und ging nun dazu über, bei jeder Festschreibung recht lange Kommentare abzugeben.

Eine Lösung könnte darin bestehen, dass Entwickler am Ende des Projekts zusammenfassende Dokumente erstellen, in denen genau angegeben ist, welche Änderungen an welchen Dateien vorgenommen wurden, welche Dateien hinzugefügt / entfernt wurden und warum.

Schlagen Sie dies dem Management hinter verschlossenen Türen vor:

Das schlimmste Szenario passiert: Alle Entwickler auf hoher Ebene gehen aus der Tür.

Während sich das Unternehmen bemüht, leere Entwicklerplätze zu besetzen, muss das Management-Team dem Kunden den Systemstatus mitteilen.

Fragen Sie sie, was ihrer Meinung nach ihre Arbeit bei der Rekonstruktion der Geschichte der App erleichtern würde:

Lesen Sie einfache englische Commits, die den sich ändernden Status des Systems klar beschreiben?

Oder möchten sie sich lieber die Codeunterschiede ansehen und sie selbst herausfinden?

Ich denke, eine Möglichkeit, sie zu überzeugen, besteht darin, den Schmerz, den Sie empfinden, tatsächlich zu erleben.

Nehmen wir zum Beispiel an, sie arbeiten an folgendem Problem: Sie haben einen Fehler, der irgendwie aufgetreten ist, als eine weitere Fehlerbehebung für denselben Code (ach, die Ironie) implementiert wurde. Es wäre großartig, dies nachzuschlagen, indem man nur die Commit-Nachrichten durchsucht (und somit herausfindet, wer es geschrieben hat).

Ein anderer Weg wäre, ihnen zu erklären, dass die Commit-Nachricht nützlich sein könnte, um einen Hinweis darauf zu geben, warum etwas auf eine bestimmte Weise implementiert wurde. Auch wenn die Festschreibungsmeldung nur "Feature X" lautet, können Sie dennoch einen Hinweis darauf erhalten, wer sie implementiert hat, sodass Sie wissen, mit wem Sie sprechen müssen.

Dies scheint jedoch nicht genug zu sein, um die beiden Antworten zu bekämpfen, die ich immer bekomme:

1. Es dauert zu lange und ich möchte nur meine Änderungen in das Repo übernehmen.
2. Es ist einfach genug, nur die Unterschiede zu betrachten.

Haben Sie versucht, Ihre Mitentwickler herauszufordern, damit sie von Kommentaren profitieren? Man kann dies aus verschiedenen Blickwinkeln betrachten:

1. Verbesserung ihres Spiels - Dies kann die schwierigere Perspektive sein, aber die Idee hier wäre, dass sie dies für eine gewisse Zeit tun und sich an die Idee gewöhnen, so dass die Gewohnheit ist, dass es länger dauern würde, in die andere Richtung zu gehen. Ein weiterer Punkt ist, wie viel Kontrolle die Kommentare bekommen würden. Wenn Sie eine kurze Geschichte im Kommentar wünschen, könnte ich ihren Punkt verstehen.
2. Subventionierung einer Änderung - Hier haben Sie eine Art Wettbewerb, um das anfängliche Buy-In zu erhalten, um dies auszuprobieren, oder um einen anderen Anreiz zu bieten, die Änderung für eine Weile durchführen zu lassen.

Was Sie noch berücksichtigen sollten, ist, wie gut Sie wissen, was Ihre Mitentwickler dort verwalten, wo Sie arbeiten. Wenn sie gestern versuchen, 10 Dinge zu erledigen, könnte ich verstehen, dass sie nicht ändern wollen, was sie als etwas sehen, das bereits funktioniert. Versuchen Sie ihnen zu sagen: "Nein, das funktioniert nicht?" Wenn ja, dann kann ich sehen, wie sie diesbezüglich ein bisschen defensiv oder kämpferisch sein können. Wenn Sie versuchen, ihnen mitzuteilen: "Während dies funktioniert, gibt es möglicherweise eine bessere Alternative ...", dann haben Sie möglicherweise eine Chance. Eine Einstellung "Heiliger als du" hier zu haben, wird dir nicht helfen, IMO.

Ein anderer Weg, dies zu betrachten ist als eine Möglichkeit für den Entwickler (en) beteiligt , um ihre Karriere zu wachsen - sie sollten besitzen die Dokumentation ihrer Arbeit.

Zusätzlich zu anderen in dem oben genannten Artikel angesprochenen Punkten besteht die Möglichkeit, die Codeänderungen zu überprüfen, um herauszufinden, wo / wann / warum eine Änderung vorgenommen wurde. Dies kann wichtig sein, wenn Sie einen schwer fassbaren Fehler ausfindig machen möchten.

Nachdem Sie sie davon überzeugt haben, dass es wichtig ist, Ihre Commits zu kommentieren, können Sie ein Skript erstellen, das Kommentare zu Commits erzwingt. Andernfalls schlägt das Skript fehl. Sie können sogar ein Minimum an Zeichen angeben, um einen aussagekräftigen Kommentar zu erhalten. Dies wird ihnen helfen, sich zu "erinnern".

Es ist jedoch wichtig, dass sie das Warum verstehen, wie @Kevin sagte, andernfalls fügen sie einfach einen zufälligen Kommentar hinzu.

Haben Sie Code-Reviews? Eine Möglichkeit besteht darin, eine Regel einzuführen, nach der ein Commit oder eine Zusammenführung von einem anderen Entwickler geprüft und genehmigt werden muss. Wenn Sie dann der Prüfer sind, müssen Sie den Entwickler, der das Commit ausführt, bitten, Ihnen zu erklären, was er getan hat. Sobald er das tut, solltest du ihn bitten, den Kommentar einzutippen, den er dir gerade gesagt hat. Wenn man die vorgenommenen Änderungen nicht kohärent erklären kann, bedeutet dies oft, dass diese Änderungen überhaupt nicht hätten vorgenommen werden dürfen.

Ich muss allerdings sagen, wie kann man etwas ablehnen, das so offensichtlich nützlich ist wie Kommentare schreiben? Es dauert nicht lange und es ist eine Zeit, die gut angelegt ist. Wenn Sie einen Kommentar schreiben, müssen Sie darüber nachdenken, was Sie gerade getan haben. Es kann sogar dazu führen, dass Sie sich die Unterschiede ansehen, um sicherzustellen, dass Sie tatsächlich das getan haben, von dem Sie glauben, dass Sie es getan haben, und dass Sie nichts Dummes getan haben.

Wenn Sie die Kommentare nicht schreiben, sind Sie schlampig und undiszipliniert. Und wenn Sie darauf bestehen, dass Sie nicht verpflichtet werden sollten, die Kommentare zu schreiben, dann sind Sie vorsätzlich fahrlässig.

Sagen Sie ihnen, dass dies der einzige Weg ist, um Ihr verfahrenstechnisches Durcheinander von 50.000 Zeilenmethoden beizubehalten, und überlegen Sie sich dann, in Zukunft einen besseren, expliziteren Code zu schreiben, damit Sie nicht mit unnötigen Kommentaren zu tun haben, die Ihre Codebasis aufblähen.

Dies ist ein Prozessänderungselement: Lassen Sie einen Manager von "x" bis "Y" entwickelten Code zuweisen, um die Qualitätssicherung des Codes einschließlich der Qualitätssicherung von Kommentaren zu überprüfen.

In meiner eigenen Organisation ist es Entwicklern nicht gestattet, eine endgültige Qualitätssicherung für ihren eigenen Code durchzuführen und diesen einzuchecken. Dies muss von einem anderen Entwickler durchgeführt werden. Ein Teil des QA-Checks sind Kommentare, also keine Kommentare, kein Einchecken. Wir führen viele Vertragsarbeiten durch, bei denen unsere "Kunst" tatsächlich das vertragliche geistige Eigentum eines anderen Menschen ist, daher müssen andere in der Lage sein, unseren Code zu verstehen und zu nutzen. Es gibt auch Zeiten, in denen Projekte nach einer langen Pause wieder bei uns eintreffen und wir 18 bis 24 Monate später in der Lage sein müssen, den Code abzurufen und zu verstehen, warum, wo und wie wir zu dem Code-Artefakt vor uns gekommen sind. Dies ist eine eigennützige Motivation zum Schreiben von Commit-Kommentaren.

Bitten Sie Ihre Mitentwickler, einige Zusammenführungen durchzuführen, den Verlauf nachzuschlagen und einige Dateien aus dem Verlauf zu vergleichen.

Möglicherweise werden Sie gebeten, am nächsten Tag Kommentare abzugeben.

Hier einige Ratschläge:

1. Versuche nicht, die Welt zu verändern. Du wirst es nicht schaffen.
2. Stattdessen sollten Sie sich darüber im Klaren sein, dass jeder etwas anders arbeitet. Keine Einheitsgröße passt zu jedem.
3. Es ist sehr böse, bestimmte Schritte für die Arbeitsprozesse der Menschen zu fordern. Das Ändern dieser Prozesse dauert 10 Jahre. Sie fordern sie auf, dies vor dem nächsten Abgabetermin zu tun.
4. Selbst einfache Prozessänderungen können lange dauern.
5. Ein kleiner Kommentar zu Commits ist viel zu unbedeutend, um diese Prozesse zu ändern.
6. Sie können davon ausgehen, dass sie qualitativ hochwertige Arbeit leisten, sollten aber genügend Freiheit haben, die Schritte selbst zu wählen. Einige mühsame Schritte sind für erfahrene Entwickler möglicherweise nicht erforderlich.
7. Wenn Sie Neulinge babysitten, sind möglicherweise stärkere Prozesse erforderlich, erfahrene Entwickler sollten sich jedoch nicht mit Blödsinn auseinandersetzen.
8. Das Auferlegen drakonischer Einschränkungen für die Art und Weise, wie gearbeitet werden muss, wird niemals funktionieren. Es kann die Menschen nur verlangsamen (kann gut sein, wenn sie zu schnell sind).
9. Es gibt viele Leute, die denken, dass ihr Weg der einzig richtige ist, um Dinge zu tun. Ich hoffe, du bist keiner von ihnen.

Wenn Ihre Quellcodeverwaltung dies zulässt, aktivieren Sie obligatorische Kommentare, um unkommentierte Commits zu verhindern. Einfach genug und jeder wird schnell merken, dass 5 Sekunden, in denen er einen Kommentar eingibt, schmerzlos sind.

Aber unkommentierte Commits gehören zu den kleinsten Negativen, die es gibt. Ich war an vielen erfolgreichen Projekten beteiligt, bei denen kein einziges Commit kommentiert wurde. Bring dein Höschen nicht drüber.