Ist es im Allgemeinen hilfreich, JIRA-Probleme in Codekommentare aufzunehmen?

8

Hin und wieder hinterlasse ich Kommentare wie

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

oder 

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

Mein Hauptanliegen dabei ist, dass dies unsere Abhängigkeit von JIRA erhöht. Daher wären diese Kommentare völlig umstritten, wenn wir in ein anderes Projektmanagementsystem migrieren würden. Ich sehe dies zwar nicht in naher Zukunft voraus, bin jedoch weiterhin besorgt über die zunehmende Kopplung von Organisationskomponenten (in diesem Fall: Code, Code-Repositorys und ein Projektmanagementsystem).

Allerdings mache ich den Vorteil, dass Verweise auf dokumentierte Designentscheidungen und Funktion Inspiration in der gesamten Codebasis sehen. Soweit ich das beurteilen kann, sind die Vorteile

  1. ein klarer Weg zum Entwerfen von Entscheidungen, der beim Debuggen und Hochfahren bestimmter Segmente unbekannten Codes hilft;
  2. weniger mehrzeilige Kommentare, wodurch Code für neue Mitwirkende sauberer / weniger einschüchternd erscheint,
  3. einen klaren Weg zu (potenziell) aktuellen technischen und nichttechnischen Interessengruppen und
  4. eine Verringerung der Anzahl der "Warum ist das hier" -Fragen aufgrund der oben genannten.
project-management coding-style communication comments jira Mr_Spock
quelle
ziemlich offensichtliches Duplikat von Ist es eine gute Praxis, mit der Ausgabenummer zu kommentieren?
Mücke
2
@gnat Es war nicht "krass", aber danke für den Hinweis.
Mr_Spock
1
Ein kleiner Vorteil ist, dass Tools wie IDEs leicht Hyperlinks zum entsprechenden Ticket erstellen können.
Axd

Antworten:

7

Ich würde versuchen, solche Kommentare zu vermeiden. Obwohl ich denke, es gibt einen Ort für sie, an dem Sie eine besonders ärgerliche Anforderung haben. Was ohne, könnte jemand den Code umgestalten wollen. z.B.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

oder ähnlich könnten Sie einen Link einfügen

//work around stolen from this stackoverflow answer http://stackoverflow....

Aber nicht aus den Gründen, aus denen Sie eine erhöhte Kopplung angeben. Tatsächlich benenne ich alle meine Feature-Filialen nach dem Ticket, für das sie bestimmt sind. So ist es möglich, alle Arbeiten bei Bedarf bis auf ein Ticket zurückzuverfolgen, obwohl der Commit-Verlauf. (Sie können auch einige clevere Auto-Close-Sachen machen, wenn Sie sich schlau fühlen.)

Nein, ich mache mir keine Sorgen um die Änderung des Ticketsystems. Mir ist jedoch klar geworden, dass es sehr selten vorkommt, dass jemand auf Tickets zurückblickt, wenn diese fertig sind.

Der Kommentar ist also nützlich, weil er zu Ihrem zukünftigen Ersatz sagt:

"Nein, ich habe keinen Fehler gemacht, jemand hat mir gesagt, dass es so sein muss. Schau! Hier ist die Ticketnummer, um es zu beweisen!"

Aber sie werden das Ticket nicht überprüfen. Das Leben ist zu kurz.

Wenn Sie es sich zur Gewohnheit machen, überall Ticketreferenzkommentare zu hinterlassen, verlieren diese ihre Wirkung. Anstatt eine Flagge zu sein "lies das, es ist super wichtig!" Sie werden einfach zu Unordnung.

Im Allgemeinen sollten die Anforderungen durch das Medium der Tests aufgezeichnet werden. Wenn die Tests bestanden wurden, müssen die Anforderungen erfüllt sein. Wir müssen uns keine Gedanken darüber machen, wie sie ursprünglich angegeben wurden.

Ewan
quelle
1
Genau. Es gibt Zeiten, in denen ich die Tracking-Datenbank rückwärts durchsucht habe, aber nicht oft. Ich bevorzuge es, die relevanten Informationen in den Codekommentaren zu haben, nur damit sie an einem Ort sind, also bevorzuge ich es nicht, Ticketnummern für bearbeitete Tickets zu setzen. Andererseits habe ich mir angewöhnt, bevorstehende / zukünftige Ticketnummern auf TODOs zu belassen, die ich möglicherweise im aktuellen Code belasse, da dies eine Vorstellung davon gibt, wann das TODO gelöst wird und ob jemand später vorbeikommt und das findet TODO für ein Ticket, das bereits geschlossen ist, ist eine Flagge, die übersehen wurde, als das zukünftige Ticket bearbeitet wurde.
Jia103
5

Für Codekommentare ist die Nützlichkeit sehr gering. Für Kommentare zur Versionskontrolle sind sie aus den unten aufgeführten Gründen sehr nützlich.

Codekommentare sollten wirklich verwendet werden, um die Absicht komplizierter Dinge zu verstehen .

Schlechte Arten von Codekommentaren:

  • Updated EHS 10/24/2015 - Wenn ich das wissen wollte, würde ich die Versionskontrolle verwenden, um herauszufinden, wer welche Zeilen geschrieben hat.
  • For spec 0.4 - Das kann Teil der Commit-Kommentare sein, aber es hilft mir nicht, den Code besser zu verstehen
  • Andere Variationen der gleichen Art von Dingen.

Wenn Codekommentare vorhanden sind, sollten sie helfen, zu verstehen, wie sich der Codeblock auf die Geschäftsdomäne bezieht.

Wenn JIRA und Ihre Versionskontrolle verknüpft sind, sind sie für Commit- Nachrichten sinnvoll .

  • Durch Referenzieren des Tickets können die Änderungen an der angeforderten Arbeit nachvollzogen werden
  • JIRA ist nicht das einzige Ticket-Tracking-Tool, das diese Synchronisierung unterstützt.

Ich empfehle ein Kommentarformat wie das folgende:

 DIGIT-827: We only need to use the following for V4 of the computation.

JIRA und fast jedes Tool mit dieser Integration ist intelligent genug, um die Ticketnummer zu erkennen und sie mit dem zu lösenden Ticket zu verknüpfen. Das bedeutet , dass eine vollständige URL ist nicht erforderlich . Es bedeutet auch , dass Sie die Vorteile bekommen und bieten sinnvolle Kommentare für die besondere alle in einer Zeile zu begehen.

Wenn Sie das Ticket in JIRA anzeigen, sehen Sie die Liste der Änderungen mit allen Kommentaren im Zusammenhang mit der Beschreibung usw.

Berin Loritsch
quelle
In Bezug auf den Kommentar zu Initialen / Datum / Beschreibung der Änderung stimme ich zwar zu, dass das Nachschlagen im Repo besser ist, ich möchte jedoch darauf hinweisen, dass sie bei meinem letzten Projekt zu dem Schluss gekommen sind, dass unsere Standard-Datei-Header mit dem anfänglichen Copyright-Jahr kombiniert mit a Das Ausführen des Softwareverlaufs im Dateikopf war ein ausreichender Beweis, um das Urheberrecht auf dem neuesten Stand zu halten. Wenn also eine Quelldatei im Jahr 2013 begann und bis heute (2018) aktualisiert wird, kann das Urheberrecht durch die Gewohnheit, den Dateikopf zu aktualisieren, ohne zusätzliche Arbeit fortgesetzt werden Minimierung der Wahrscheinlichkeit eines Zeitraffers.
Jia103
@ jia103, Copyright-Header sind eine andere Sache als das Kommentieren einer Zeile, die an diesem oder jenem Datum mit den Initialen einer Person geändert wurde, die im Moment möglicherweise Teil des Teams ist oder nicht. Das eine ist eine legale Sache, das andere sind einfache redundante Informationen, die keinen Kontext für das Verständnis des Codes daneben bieten.
Berin Loritsch
2

Ja, aber nur in seltenen Fällen.

Im Allgemeinen stelle ich mir vor, dass der größte Teil des Codes in Verbindung mit einem JIRA-Ticket geschrieben wird, daher würde ich ihn nicht routinemäßig mit der Ticket-ID kommentieren - dafür ist Git verantwortlich. In einigen Fällen kann der Code jedoch kontraintuitiv sein - vielleicht funktioniert die naheliegendste Art, den Code zu schreiben, nicht, und es gab einige Diskussionen darüber, warum nicht auf dem Ticket. In diesem Fall würde ich in Betracht ziehen, einen Kommentar mit der Ticketreferenz hinzuzufügen.

Wenn ein Teil des Codes einen bekannten Fehler in einem anderen Teil umgehen muss, würde ich auch in Betracht ziehen, eine Ticketreferenz hinzuzufügen.

Ich denke nicht, dass dies Sie zu eng an JIRA bindet. Wenn Sie von JIRA auf ein alternatives System migrieren möchten, können Sie Ihre JIRA-Probleme als CSV exportieren und in das andere System importieren. Die Problem-ID kann sich während dieses Vorgangs ändern, Sie sollten jedoch in der Lage sein, die JIRA-Ticket-ID irgendwo auf den importierten Tickets beizubehalten.

bdsl
quelle
1

Fügen Sie Jira-Probleme in die Commit-Kommentare ein und verknüpfen Sie die Commits mit einem Plugin mit dem eigentlichen Jira.
Unsere Commit-Nachrichten beginnen mit:

JIRA: XBVS-1222 Fixes bugs...

Zum Beispiel verbinden dann Hooks zwischen Bitbucket und Jira die Commits mit dem Jira. Dann ist es leicht zu erkennen, auf welche Jira es sich in Eclipse bezieht, indem Sie beispielsweise mit der rechten Maustaste auf die Zeilennummer klicken und "Revisionsverlauf anzeigen" auswählen. Ich denke, das nennt man sowieso so. Ihre Jira-Ausgabenummer und -Kommentare werden in der Zeilennummernspalte hervorgehoben, und wenn Sie mit der Maus darüber fahren, werden die Details angezeigt.

bot_bot
quelle
1
Ein einzelnes Jira-Problem entspricht einem einzelnen Zweig, und jedes Commit wird mit der Jira-ID für ein bestimmtes Problem versehen, genau wie Sie es empfehlen. Ich habe dies für eine lange Zeit verwendet und mit Git-Schuld ist es eine großartige Möglichkeit, Codeänderungen und ihre Gründe zu verfolgen, ohne den tatsächlichen Code mit nutzlosen Kommentaren zu verschmutzen.
Andy
1

Es ist sicherlich keine schreckliche Praxis, JIRA-Probleme in Codekommentare aufzunehmen, aber diese Technik verbindet zwei unterschiedliche Probleme (Probleme und Code) eng / manuell und kann Aktualisierungen mehrerer Systeme / Standorte erfordern (JIRA, überall in der Quelle, in der das Problem erwähnt wird). Versionskontrollverlauf).

Codekommentare sind im Allgemeinen problematisch, da sie häufig nicht aktualisiert werden.

Ein besserer Ansatz wäre, eine Möglichkeit zu finden, Ihr Problemverfolgungssystem in Ihr Versionskontrollsystem zu integrieren, damit die beiden Probleme auf automatisierte Weise getrennt verwaltet werden können.

mcknz
quelle