Gute Idee, Fehlernummern in einen Kommentar am Anfang der Quelldatei einzufügen? [geschlossen]

40

Ist es eine gute Praxis, die Fehlernummern in der Datei selbst in einem Kopfzeilenkommentar abzulegen?

Die Kommentare würden ungefähr so ​​aussehen:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Es scheint hilfreich zu sein, aber wird es als schlechte Praxis angesehen?

Geek
quelle
23
Die Frage, die ich stellen würde, lautet: "Was können Sie mit eingebetteten Fehlernummern tun, die Sie nicht bereits mit Ihrer Fehlerdatenbank tun können?" Ich kann mir keine konkreten Anwendungsfälle vorstellen.
M. Dudley
6
@JensG Deshalb setzen Sie es in die Commit-Nachricht und ein login der Datei gibt Ihnen so ziemlich das gleiche, aber ohne die Datei zu
überladen
1
@JensG Und wenn Sie Punkte oder Hunderte von Fehlern in einer bestimmten Datei korrigiert haben? Die offensichtliche Antwort ist, dass Sie die veralteten IDs regelmäßig löschen, aber dann wieder das VC-Protokoll
durchsuchen
3
Diese Frage ist Gegenstand des Artikels von Ars Technica. Sollten wir Fehler im Header einer Quelldatei auflisten? (15 Tage nach dem Absenden dieser Frage veröffentlicht).
Peter Mortensen

Antworten:

107

Ich habe dies bereits zuvor gesehen, sowohl manuell von Autoren als auch automatisch von Skripten und Triggern, die in Versionskontrollsysteme integriert sind, um der Datei Autoren-, Eincheckkommentar- und Datumsinformationen hinzuzufügen.

Ich denke, beide Methoden sind aus zwei Hauptgründen ziemlich schrecklich. Erstens werden Unordnung und Rauschen in die Datei eingefügt, insbesondere wenn diese Kommentare älter werden und für den aktuellen Status der Datei keine Rolle mehr spielen. Zweitens sind es doppelte Informationen von dem, was bereits im Versionskontrollsystem gepflegt ist, und wenn Sie ein modernes Versionskontrollsystem verwenden, das Änderungssätze unterstützt, gehen tatsächlich Informationen über Änderungen verloren.

Ziehen Sie gegebenenfalls die Integration in Ihr Fehlerverfolgungssystem in Betracht. Mit einigen Tools können Sie eine Fehler- oder Aufgaben-ID-Nummer in einem Check-in-Kommentar mit einem Element im Tracking-Tool verknüpfen. Wenn Sie alle Ihre Fehler, Verbesserungswünsche und Arbeitsaufgaben im Tool haben, können Sie die Verknüpfung auf diese Weise bereitstellen. Dies ist natürlich mit der Kehrseite einer Abhängigkeit von diesen Tools für das Projekt verbunden.

Thomas Owens
quelle
2
"Wenn Sie ein modernes Versionskontrollsystem verwenden, das Änderungssätze unterstützt, gehen tatsächlich Informationen über Änderungen verloren." - Können Sie bitte näher darauf eingehen?
Geek
10
@Geek Ich bin mir nicht sicher, was ich erklären soll. Wenn Sie sich eine Datei ansehen, die auf eine Fehler-ID verweist, werden keine Änderungen an anderen Dateien infolge desselben Fehlers angezeigt, es sei denn, Sie durchsuchen die Dateien. Das ist ein Änderungssatz - eine Sammlung von Dateien, die zusammen eingecheckt wurden.
Thomas Owens
9
Ich würde auch hinzufügen, dass, wenn Sie auf ein neues Bug-Tracking-System umsteigen, diese Zahlen alle sofort wertlos werden. Ich habe das bei meinem aktuellen Job erlebt, wo einige Kommentare Zahlen von Bug-Tracking-Software enthalten, die seit 10 Jahren nicht mehr verwendet wurden.
17 von 26
2
Nach dem Umstieg auf das neue Bug-Tracking-System werden sie so nützlich, als wären sie nie da. Aber wenn sie irgendwann einen Wert liefern und jetzt keinen negativen Wert mehr liefern, warum nicht?
Cruncher
@ 17of26 - Ich würde mir vorstellen, dass Sie alte Bugs / Probleme mit neuen verknüpfen könnten, wenn Sie keinen anderen Mechanismus als einen Kommentar wie "old issue tracker bug 1234" verwenden würden.
Kenny Evitt
42

Es gibt genau einen Fall, in dem ich dies tun würde, nämlich als Teil einer Warnung für zukünftige Programmierer: "Rufen Sie die Funktion foo()hier nicht direkt auf; dies hat den Fehler # 1234 verursacht, nämlich ...", und dann eine kurze Beschreibung der Fehler folgt.

Und wenn sich der Code so geändert hat, dass keine Versuchung besteht, foo()direkt anzurufen , entfernen Sie diesen Kommentar. Es würde den Code nur irritieren und in die Luft jagen.

rem
quelle
19
Vielleicht bin ich ein bisschen hart im Nehmen, aber wenn foo()man nicht direkt aufruft, sollte der Code so strukturiert sein, dass es nicht sein kann.
MetaFight
20
Oh, ich habe versucht, etwas als Beispiel zu schreiben , um den Text konkreter zu machen - nimm mich nicht zu wörtlich. Ein besserer Fall wäre ein Fall, in dem Sie eine externe Bibliothek verwendet haben und die Funktion, die Sie normalerweise für einen bestimmten Zweck verwenden würden, einen Fehler aufwies. Dann wäre ein Kommentar "Hier nicht anrufen foo()" sinnvoll.
Rem
16

Es ist eine insgesamt schreckliche Praxis. Es erhöht den Aufwand, um einen Effekt zu erzielen, bei dem es sich um eine reine Vervielfältigung handelt. Mit anderen Worten, das Einzige, was über die reine Verwendung von Festschreibungsprotokollen hinausgeht, ist die Möglichkeit, Inkonsistenzen zu erzeugen. Ihre Quelldateien werden mit unbegrenzten Mengen von Dingen überfüllt, die Sie nie anschauen.

Der einzige Vorteil, den ich überhaupt feststellen kann, ist, dass Sie den Quellverlauf ohne Zugriff auf die Versionskontrolle rekonstruieren können, z. B. beim Studieren eines Ausdrucks. Aber nur sehr wenige Menschen sind kompetent genug, um die Feinheiten der Softwareentwicklung zu verfolgen, und sind gleichzeitig nicht in der Lage, die Versionskontrolle zu verstehen.

Kilian Foth
quelle
Wie viele Fehler genau sind Ihrer Meinung nach in einer Datei möglich und wenn es so viele gibt, ist es wahrscheinlich Zeit für ein Umschreiben.
Andy
11

Nein.

Das war es, was die Leute taten, bevor sie ein Versionskontrollsystem verwendeten (dh als Quellcode nur Backups in zip-Dateien waren).

Neil Barnwell
quelle
2
Dies war eine Art Versionskontrollsystem (und eines, das ich bereits 2006 in Softwarehäusern im Einsatz gesehen habe und das heute zweifellos irgendwo im Einsatz ist).
jwenting
1
@jwenting Ich habe auf dieser Website Fragen von Leuten gesehen, die das Pech haben, gerade in Geschäften zu arbeiten, in denen das derzeit üblich ist :-(
Carson63000
Wir verwenden ein großartiges Quellcodeverwaltungssystem. Niemand außer mir gibt beim Einchecken von Code Kommentare ein. <Achselzucken> Ich kommentiere bestimmte Dinge (wie PLSQL, das nicht immer von SCM verfolgt wird). Ich kommentiere meinen Code, um ihn zu erklären, binde ihn aber nie auf bestimmte Fehler zurück, sondern beziehe mich beim Einchecken immer auf Fehler in SCM-Commit-Kommentaren. Hoffentlich wird es irgendwann jemandem gefallen.
Pedantic
11

Es ist meiner Meinung nach eine sehr schlechte Idee. Nach der Revision 100 haben Sie 90% Kommentare und 10% Code. Ich würde das nicht als sauber und lesbar betrachten.

Der einzige Punkt, den ich sehe, ist, wenn Sie Ihren Code zwischen SCCs austauschen müssen und aus irgendeinem Grund den Verlauf nicht zwischen den beiden Systemen übertragen können (aber selbst wenn Sie die Verlaufskommentare auf diese Weise speichern, verlieren Sie den Diff-Verlauf Das Speichern der Kommentare hilft Ihnen also nur ein wenig.

Doc Brown
quelle
8

Ich sehe, dass jeder gegen die Idee ist und einen historischen Grund (Ära vor der Quellcodeverwaltung) dafür angibt, warum die Leute das getan haben.

In meinem derzeitigen Unternehmen befolgen Datenbankentwickler diese Vorgehensweise und kennzeichnen zusätzlich die Fehlernummer um den Code. Ich finde das manchmal hilfreich, wenn Sie einen Fehler im Code sehen und sofort die Fehlerbehebung finden, die dieses Problem verursacht hat. Wenn wir diese Informationen nicht in meinem Datenbankpaket haben, ist es sicherlich nicht einfach, die Hauptursache für diese Implementierung zu finden.

Ja, es überfrachtet den Code, aber es hilft dabei, den Grund dafür zu finden, warum dieser Code vorhanden ist.

Parvez
quelle
3
Absolut. Manchmal habe ich das leichte Gefühl, dass Programmierer vor Redundanz entsetzt sind und es vermeiden, auf unterschiedliche Weise auf dieselben Informationen zuzugreifen. Das ist sehr interessant, da Programmierer in der Regel auch von schlechter Leistung entsetzt sind und daher Caches in ihren Programmen verwenden. Aber das Zwischenspeichern von Fehlernummern im Code neben der Stelle, an der sie am nützlichsten sind, wird als schlecht angesehen? Mmmh.
JensG
Es gibt oft eine andere Möglichkeit, an diese Informationen zu kommen (bei dem Projekt, an dem ich arbeite, wäre es right click > Team > Show Annotations, die Hauptschuld der aktuellen Datei zu ermitteln), aber der Unterschied ist, dass es bei Kommentaren Auffindbarkeit gibt - sie können auf Sie losgehen - und mit Anmerkungen muss man sich bewusst dafür entscheiden, sie zu suchen.
David Conrad
Überlegen Sie, entscheiden Sie, klicken Sie, klicken Sie, klicken Sie, scrollen Sie. Deshalb habe ich "Caching in Code" gesagt. Wenn es da ist, sehe ich es einfach.
JensG
2
@JensG Interessante Sicht. Caches können die Leistung verbessern, verursachen aber auch Kosten. Wenn der Cache durch redundante menschliche Anstrengungen gefüllt, aktualisiert, ungültig gemacht, geleert usw. werden muss, stelle ich das Kosten-Nutzen-Verhältnis in Frage, insbesondere angesichts der Tatsache, wie schrecklich Menschen sind, solche denormalisierten Konstruktionen synchron zu halten.
Jeffrey Hantin
7

Einer der Punkte im Joel-Test ist

Hast du eine Bug-Datenbank?

Solche Informationen könnten in einer Bug-Datenbank gespeichert werden, wenn Sie denken, dass sie wichtig sind, aber sie würden nur Rauschen in Kommentaren verursachen.

Pierre Arlaud
quelle
1
Siehe das Beispiel in der Frage - die Kommentare würden auf die Bug-Datenbank
verweisen
@ Izkata Aber das ist der Punkt. Die Datenbank selbst kann ein "Kommentar" -Feld mit dem Kommentar enthalten. Die Frage ist nicht, ob es sich um eine Bug-Datenbank handelt oder nicht, sondern ob es eine gute Idee ist, diese in der Quelldatei zu behalten. Ich denke, auch wenn es sich um Kommentare handelt, sollten sie in der Datenbank selbst aufbewahrt werden, denn dafür ist sie gedacht.
Pierre Arlaud
6

Ich denke, Sie haben hier zwei Probleme. Erstens, warum sollten Sie sich nur auf das Diff verlassen, wenn Sie auf den meisten Systemen Revisionskommentare eingeben können? Wie bei guten Codekommentaren stellen Sie fest, warum die Änderung vorgenommen wurde und nicht nur die Änderung selbst.

Zweitens sollten Sie, wenn Sie über diese Funktion verfügen, alle am selben Ort ablegen. Es ist nicht erforderlich, in der Datei nach markierten Codezeilen zu suchen, die nicht mehr benötigt werden. Kommentare im Arbeitscode sollen Ihnen erklären, warum er auf diese Weise codiert ist.

Sobald Sie dies in die Praxis umsetzen, erleichtern Ihnen die Gewohnheiten, an denen Sie arbeiten können, die Arbeit an der Codebasis.

Das zugehörige Bug- und Feature-Tracking sowie die Gründe für das Ändern dieser Datei können Ihnen eine Vorstellung davon geben, wie tief Sie in den Verlauf eintauchen und möglicherweise die Unterschiede untersuchen müssen. Ich hatte die Bitte, "zur ursprünglichen Formel zurückzukehren". Ich wusste genau, wohin ich gehen musste, und habe nur ein oder zwei Unterschiede überprüft.

Persönlich sieht auskommentierter Code aus wie ein laufendes Projekt für ein Problem, das durch Ausprobieren gelöst wird. Holen Sie sich dieses Chaos aus dem Produktionscode. Wenn Sie Codezeilen einfach ein- und ausschieben können, ist es einfacher, sich zu verwechseln.

JeffO
quelle
2

Wenn Sie kein VCS mit Festschreibungsmeldungen und kein Fehlerverfolgungssystem haben, in dem Sie Kommentare hinterlassen können, ist dies eine und nicht die optimale Option, um Änderungen im Auge zu behalten.
Besser ist es, eine Tabelle mit diesen Informationen zu haben, oder wenn Sie sich in einer Umgebung ohne solchen "Luxus" befinden, eine Textdatei, die sich irgendwo in der Nähe Ihrer Quellen befindet.
Aber ich würde empfehlen, wenn Sie sich in einer solchen Umgebung befinden, ein Argument für die Investition in ein VCS- und Bug-Tracking-System zu entwickeln :)

jwenting
quelle
2

Denken Sie daran - der Code ist oft länger als die Tools, die ihn unterstützen. Anders gesagt, der Issue Tracker, die Versionskontrolle und alle anderen Skripte werden sich im Laufe der Entwicklung weiterentwickeln. Informationen gehen verloren.

Obwohl ich dem zustimme, ist es ärgerlich, eine Datei zu öffnen und ihren Verlauf zu verstehen, ohne auf die Tools zurückzugreifen. Dies war immer sehr hilfreich - insbesondere, wenn ich den Code pflege.

Persönlich denke ich, dass sowohl für die Tools als auch für das In-Code-Protokoll Platz ist.

ggb
quelle
2

Ich weiß, dass Git dies nicht tut und die einfache Antwort lautet: "Warum um alles in der Welt sollte es dorthin gehen?"

Es ist im Allgemeinen weniger modular aufgebaut. Bei dieser Lösung sind Dateien nun eine Mischung aus Inhalten und Metadaten. Amazon S3 ist ein weiteres Beispiel für einen Dienst zum Speichern von Dateien, bei dem den Dateien kein YAML -Text oder ähnliches hinzugefügt wird .

Jeder Benutzer einer Datei muss diese zuerst über das Versionskontrollsystem verarbeiten. Dies ist eine enge Kopplung, z. B. wird Ihre Lieblings-IDE kaputt gehen, wenn sie Ihr VCS nicht unterstützt.

djechlin
quelle
2

Nein, es ist keine gute Praxis, Ihre Fehlerbehebungen als Kommentare im Code zu verfolgen. Dies erzeugt nur Unordnung.

Ich werde dasselbe auch für die von Ihnen erwähnte Copyright-Nachricht sagen. Wenn niemand außerhalb Ihres Unternehmens diesen Code jemals sehen wird, gibt es keinen Grund, eine Copyright-Meldung hinzuzufügen.

Wenn Sie eine Versionsverfolgungssoftware ( Git , SVN usw.) verwenden, sollten Sie diese Notizen in Ihre Commit-Nachrichten aufnehmen. Niemand möchte die Überschriften jeder Codedatei durchsuchen, um Versionshinweise zu generieren oder einen Überblick darüber zu erhalten, welche Änderungen vorgenommen wurden. Diese Änderungsprotokolle sollten alle zusammen gespeichert werden, entweder in Ihrem Versions-Tracking-Verlauf, in Ihrem Defect-Tracker oder in beiden.

Wenn Sie eine gute Lektüre zu diesem Thema suchen, empfehle ich Kapitel 4 von Clean Code .

Brian
quelle
Urheberrechtshinweise dienen auch dazu, Mitarbeiter (geringfügig redundant) darauf aufmerksam zu machen, dass die Datei dem Arbeitgeber gehört. Und schreckt vielleicht illegal Sharing (auch von den Mitarbeitern), zu urteilen, wie viele Leute scheinen , dass das Urheberrecht nur zu denken gilt , wenn es ist ein Hinweis.
Bernd Jendrissek
1

Ich denke, es gibt andere Elemente in dieser Diskussion, die oft vergessen werden, aber es gibt Fälle, in denen ein Revisionskommentar für ein Team schnell ist.

Wenn Sie in einer Teamumgebung mit einer gemeinsam genutzten Codebasis arbeiten und mehrere Teammitglieder möglicherweise in denselben Codebereichen arbeiten, kann es sehr nützlich sein, einen kurzen Revisionskommentar in den richtigen Bereich (Methode oder Klasse) zu setzen, der angibt, dass eine Änderung vorgenommen wurde Schnelle Lösung von Zusammenführungs- oder Eincheckkonflikten.

Wenn Sie in einer Umgebung arbeiten, in der mehrere (Feature-) Zweige involviert sind, kann eine dritte Person (Build-Master) leichter erkennen, was zu tun ist, um potenzielle Konflikte zu lösen.

Jedes Mal, wenn Sie sich von der IDE entfernen und jemanden fragen müssen, warum er etwas geändert hat, wirkt sich dies negativ auf die Produktivität beider Teammitglieder aus. Ein kurzer Hinweis im richtigen Umfang kann dazu beitragen, den größten Teil dieser Unterbrechung zu verringern oder zu beseitigen.

StingyJack
quelle
3
Frage ist , Kommentar am Anfang der Quelldatei, direkt nach dem Copyright - Meldung - das hat nichts mit Kommentaren in den engeren Bereichen zu tun
gnat
Alle Antworten hier sprechen jedoch genau darüber. Würde ich die Klassendatei nicht als Gültigkeitsbereich kommentieren, wenn ich wesentliche Änderungen an der gesamten Klassendatei vornehme (Neuorganisation oder Formatierungskorrektur)?
StingyJack
0

Alle Fehlerinformationen, die direkt mit einem Codeteil verknüpft sind, werden irrelevant, wenn die Integrität der gesamten Änderung durch eine sukzessive Korrektur geändert wird.

Früher war es üblich, der Funktionsübersicht Informationen hinzuzufügen, wenn wir uns auf externe Tools (z. B. Javadocs) stützen mussten, um Versionshinweise aus dem Code zu erstellen. Bei modernen Tools zur Versionskontrolle ist dies meistens nutzlos oder überflüssig.

Als Kommentar in einem sehr modularen Codeteil könnte es nur Sinn machen, wenn man auf eine obskure oder nicht stellare Codierung zurückgreifen muss, die zukünftige Entwickler - ohne den Grund dafür zu kennen - zu ändern versucht wären - wie bei einer Umgehung von a Bibliotheksfehler / -mangel.

Fiammetta Castaldi
quelle
0

Ich würde solche Informationen definitiv nicht am Anfang der Datei einfügen - normalerweise gehört so etwas in ein Ticketsystem.

Es gibt jedoch einige Fälle, in denen Verweise auf das Ticketsystem und / oder andere Dokumentationen sinnvoll sind. Zum Beispiel, wenn es eine ausführliche Erläuterung des Designs oder eine Beschreibung von Alternativen gibt. Oder Informationen, wie man Dinge testet, oder Erklärungen, warum es genau so gemacht wurde. Wenn das kurz ist, gehört es in die Datei selbst; Wenn es lang ist und / oder sich um ein größeres Bild handelt, möchten Sie es wahrscheinlich an einer anderen Stelle ablegen und darauf verweisen.

hstoerr
quelle
dies scheint nicht wesentlichen Wert hinzufügen , was bereits in früheren Antworten gepostet wurde
gnat
0

Das Projekt, dem ich derzeit bei der Arbeit zugewiesen bin, hatte diese Art von Fehlernummernliste am Anfang jeder Datei. Allerdings hängt keiner der Entwickler, die noch am Projekt beteiligt sind, mehr daran an. Die meisten von ihnen halten es für eine nutzlose Verschwendung von Speicherplatz, da es der Verfolgung von Fehlerbindungen in einer Datei mit unserem Versionskontrollsystem weit unterlegen ist.

In bestimmten wichtigen Dateien, die viele Korrekturen und Verbesserungen erfahren haben, sind diese Listen so umfangreich geworden, dass Sie einen Bildlauf durchführen müssen, um zum Code zu gelangen. Beim Greifen auf diese Listen kann es zu mehreren Fehlalarmen kommen, da jeweils ein kurzer Fehlertitel oder eine kurze Beschreibung aufgeführt wird.

Kurz gesagt, diese Listen sind bestenfalls nutzlos und im schlimmsten Fall eine massive, chaotische Verschwendung von Speicherplatz, die das Durchsuchen und Auffinden von Code erschwert.

Fred Thomsen
quelle