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

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?

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.

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.

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.

Nein.

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

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.

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.

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.

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.

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

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.

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.

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 .

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.

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.

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.

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.