Haben Sie spezielle Kommentare zu Bug-Fixes in Ihrem Code verwenden?

https://stackoverflow.com/questions/123936

comments

02-07-2019
|

Frage

Einige meiner Kollegen verwenden spezielle Kommentare auf ihre Fehlerkorrekturen, zum Beispiel:

// 2008-09-23 John Doe - bug 12345
// <short description>

Ist das sinnvoll?
Haben Sie Bug-Fixes in besonderer Weise kommentieren?

Bitte lassen Sie mich wissen.

Lösung

Ich habe nicht in den Kommentaren so sagt, hält das Quellcodeverwaltungssystem bereits, dass die Geschichte und ich bin bereits in der Lage, die Geschichte einer Datei zu protokollieren.

ich in den Kommentaren stellen, die beschreiben, warum etwas nicht offensichtlich ist, obwohl getan. Also, wenn der Bug-Fix macht den Code weniger vorhersehbar und klar, dann erkläre ich, warum.

Andere Tipps

Im Laufe der Zeit können diese ansammeln und Unordnung hinzuzufügen. Es ist besser, den Code klar zu machen, fügen Sie alle Kommentare zu verwandten gotchas, die nicht offensichtlich sein können, und den Fehler detailliert in dem Trackingsystem und Repository zu halten.

Ich neige dazu, nicht in der eigentlichen Quelle zu kommentieren, weil es schwierig sein kann, auf dem neuesten Stand zu halten. Allerdings kann ich setzen Kommentare in meinem Source-Control-Protokoll und issue tracker verbindet. z.B. Ich könnte so etwas wie dies in Perforce tun:

[Bug-Id] Problem mit xyz-Dialog. Verschoben Größencode abc und jetzt Initialisierung später.

Da ist in meinem issue tracker werde ich tun, so etwas wie:

Feste in Änderungsliste 1234.

Verschoben Code abc Sizing und jetzt   Initialisierung später.

Weil dann eine gute historische Markierung gelassen wird. Auch macht es einfach, wenn Sie wissen wollen, warum eine bestimmte Codezeile eine gewisse Art und Weise ist, können Sie nur sehen Sie die Datei Geschichte. Sobald Sie den Code-Zeile gefunden haben, können Sie meine Commit-Kommentar und deutlich sehen, lesen, welche Fehler es war und wie ich es festgelegt.

Nur wenn die Lösung war besonders klug oder schwer zu verstehen.

ich in der Regel meinen Namen, meine E-Mail-Adresse und das Datum zusammen mit einer kurzen Beschreibung das, was ich verändern, ist das, weil als Berater oft ich andere Leute Code zu beheben.

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

So wird der Code-Inhaber, oder die Leute nach mir kommt in, herausfinden, was passiert ist, und sie können mit mir in Kontakt treten, wenn sie müssen.

(ja, leider öfter als nicht, dass sie keine Quelle Kontrolle hat ... für interne Sachen verwende ich TFS-Tracking)

Während dies wie eine gute Idee zu der Zeit zu sein scheint, wird es schnell aus der Hand. Solche Informationen können besser mit einer guten Kombination von Quellkontrollsystem und Bug-Tracker erfasst. Natürlich, wenn es etwas heikel los, ein Kommentar die Situation beschreibt, in jedem Fall wäre hilfreich, aber nicht das Datum, Name oder Fehlernummer.

Die Codebasis arbeite ich zur Zeit bei der Arbeit an ist so etwas wie 20 Jahre alt und sie scheinen viele Kommentare wie vor Jahren hinzugefügt zu haben. Glücklicherweise hielten sie es vor ein paar Jahren zu tun, nachdem sie alles zu CVS in den späten 90er Jahren umgewandelt. Allerdings sind solche Kommentare immer noch über den gesamten Code übersät und die Politik jetzt „entfernen, wenn Sie arbeiten direkt an diesem Code, aber ansonsten lassen sie“. Sie sind oft sehr hart vor allem zu folgen, wenn der gleiche Code hinzugefügt und entfernt mehrmals (ja, es passiert). Sie enthalten auch nicht das Datum, aber die Fehlernummer enthalten, die Sie in einem archaischen System gehen würden suchen, um das Datum zu finden, so dass niemand tut.

Kommentare wie diese sind, warum Subversion können Sie auf jedem Commit einen Protokolleintrag eingeben. Das ist, wo Sie das Zeug legen sollten, nicht im Code.

ich es tun, wenn die Bug-Fix etwas beinhaltet, das nicht einfach ist, aber mehr als oft nicht, wenn der Bugfix eine lange Erklärung bedarf ich es als ein Zeichen nehmen, dass das Update nicht gut entwickelt wurde. Gelegentlich habe ich um eine öffentliche Schnittstelle zu arbeiten, die nicht so ändern kann, ist dies jedoch häufig die Quelle dieser Arten von Kommentaren zu sein, zum Beispiel:

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

In anderen Fällen sind die Source-Control-Commit-Nachricht ist, was ich verwende, um die Änderung zu annotieren.

Während ich dazu neigen, einige Kommentare auf Fehler in dem Code bei der Arbeit zu sehen, meine persönliche Präferenz ist die Verknüpfung ein Code zu einem Fehler zu begehen. Als ich man sagen, meine ich wirklich einen Fehler. Danach können Sie immer zu den vorgenommenen Änderungen sehen und wissen, welche Fehler diese angewendet wurden.

Das Kommentarstil ist äußerst wertvoll in einem Multi-Entwicklern Umfeld, in dem es eine Reihe von Fähigkeiten und / oder betriebswirtschaftlichen Kenntnissen über die Entwickler (z - überall)

Um die erfahrenen knowledgable Entwickler der Grund für eine Änderung offensichtlich sein, aber für neue Entwickler, dass Kommentar wird sie zweimal überlegen, und weitere Untersuchungen, bevor mit ihm durcheinander. Es hilft ihnen auch mehr darüber zu erfahren, wie das System funktioniert.

Oh, und eine Notiz aus Erfahrung über die „Ich, dass gerade in dem Quellensteuersystem“ Kommentare:

Wenn es nicht in der Quelle ist, es ist nicht geschehen.

Ich kann nicht die Anzahl, wie oft die Quelle der Geschichte für Projekte zählt aufgrund Unerfahrenheit mit der Source-Control-Software verloren wurde, falsche Verzweigung Modelle etc. Es gibt nur an einer Stelle der Änderungshistorie nicht verloren -. und das ist in der Quelldatei

ich es in der Regel dort die erste Stelle setzen, dann schneiden ‚n den gleichen Kommentar einfügen, wenn ich überprüfen Sie es in.

Nein, habe ich nicht, und ich hasse es der Code wie dieser Wurf Graffiti haben. Bug-Nummern können in der Commit-Nachricht an das Versionskontrollsystem verfolgt werden, und durch Skripte relevant Commit-Nachrichten in das Bug-Tracking-System zu schieben. Ich glaube nicht, dass sie in dem Quellcode gehören, wo zukünftige Änderungen werden nur Dinge verwirren.

Oft wird ein Kommentar wie, dass mehr verwirrend ist, da man nicht wirklich Zusammenhang haben Sie, was der ursprüngliche Code aussah, oder das Original schlechtes Verhalten.

In der Regel, wenn Ihr Bug-Fix jetzt den Lauf Code macht RICHTIG, lassen Sie einfach einfach ohne Worte. Es besteht keine Notwendigkeit richtigen Code zu kommentieren.

Manchmal macht die Bug-Fix Dinge seltsam aussehen, oder die Bug-Fix testen für etwas, das aus dem üblichen heraus ist. Dann könnte es sinnvoll sein, um einen Kommentar zu haben - in der Regel der Kommentar sollte auf die „Fehlernummer“ aus dem Bug-Datenbank zurückgreifen. Zum Beispiel könnten Sie einen Kommentar haben, der sagt „Bug 123 - Konto für merkwürdiges Verhalten, wenn der Benutzer in 640 x 480 Bildschirmauflösung ist“.

Wenn Sie Kommentare hinzufügen, dass nach einigen Jahren den Code beibehalten werden Sie so viele Fehler haben Kommentare beheben Sie den Code nicht lesen würde.

Aber wenn Sie etwas, das richtige Aussehen (aber einen subtilen Fehler haben) in etwas, das komplizierter ist es schön, ein kurzer Kommentar hinzufügen zu erklären, was Sie getan haben, so dass der nächste Programmierer dieser Code zu erhalten ist es nicht ändern zurück, weil er (oder sie) denkt, dass Sie über komplizierte Dinge ohne guten Grund.

Nein. Ich benutze Subversion und geben immer eine Beschreibung meiner Motivation eine Änderung für die Begehung. Ich in der Regel tun, die Lösung auf Englisch nicht neu formulieren, statt ich die Änderungen zusammenfassen.

Ich habe auf einer Reihe von Projekten gearbeitet, wo sie Kommentare im Code setzen, wenn Fehlerkorrekturen vorgenommen wurden. Interessanterweise und wahrscheinlich nicht zufällig waren diese Projekte, die entweder keine Art von Quellensteuer Werkzeug verwendet hatten oder wurden beauftragt, diese Art von Konvention vom Management von Fiat zu folgen.

Ganz ehrlich, ich weiß nicht wirklich den Wert sehen dies für die meisten Situationen zu tun. Wenn ich wissen will, was sich verändert, werde ich an der Subversion Protokoll aussehen und die diff.

Nur meine zwei Cent.

Wenn der Code korrigiert wird, der Kommentar nutzlos ist und nie interessant jemand - nur Lärm.

Wenn der Fehler nicht behoben ist, ist der Kommentar falsch. Dann macht es Sinn. So lassen nur solche Kommentare :), wenn Sie nicht wirklich den Fehler behoben.

diejenigen lokalisieren Kommentar verfasst wir verwenden DKBUGBUG - die David Kelley fix und Kritiker bedeutet einfach Identität, Ofcourse werden fügen wir Datum und andere Bug-Tracking-Nummer VSTS etc zusammen mit diesem.

Sie duplizieren nicht Meta-Daten, die Ihr VCS für Sie behalten wird. Daten und Namen sollen von der VCS in die automatisch hinzugefügt werden. Losnummern, Manager / Benutzernamen, der die Änderung angefordert, usw. sollten in VCS Kommentare, nicht den Code.

Statt diese:

// $ DATE $ NAME $ TICKET // nützlich Kommentar auf die nächste arme Seele

Ich würde dies tun:

// nützlich Kommentar auf die nächste arme Seele

Wenn der Code auf einer Live-Plattform ist, weg von den direkten Zugriff auf die Quellcodeverwaltungsrepository, dann werde ich Kommentare hinzufügen die Änderungen als Teil der Lösung für einen Fehler auf dem Live-System zu unterstreichen.

Ansonsten nicht die Nachricht, die Sie beim Einchecken geben sollte alle Informationen enthalten, die Sie benötigen.

prost,

Rob

Wenn ich Fehlerbehebung machen / Erweiterungen in Bibliotheken von Drittanbietern / Komponente ich oft einige Bemerkungen machen. Dies macht es einfacher zu finden und die Änderungen zu bewegen, wenn ich eine neuere Version der Bibliothek / Komponente verwenden müssen.

In meinem eigenen Code, den ich kommentiert selten Fehlerbehebungen.

Ich arbeite nicht auf mehreren Personen Projekte, aber ich manchmal Kommentare über einen bestimmten Fehler zu einer Einheit Test hinzuzufügen.

Denken Sie daran, es gibt nicht so etwas wie Wanzen, nur unzureichend getestet.

Da ich so viel wie möglich TDD tun (alles andere ist sozialer Selbstmord, weil jede andere Methode wird Sie zwingen, endlose Stunden zu arbeiten), ich selten Fehler beheben.

Die meisten der Zeit, die ich besondere Bemerkungen wie dieser an den Code hinzu:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

klingt hart, aber die meisten Menschen, die sich selbst als „Entwickler“ nennen, verdienen keine weiteren Bemerkungen.

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow