Einige meiner Kollegen verwenden spezielle Kommentare auf ihre Fehlerbehebungen, zum Beispiel:Verwenden Sie spezielle Kommentare zu Fehlerbehebungen in Ihrem Code?
// 2008-09-23 John Doe - bug 12345
// <short description>
Does this Sinn?
Kommentieren Sie Bugfixes auf besondere Weise?
Bitte lassen Sie es mich wissen.
Ich gebe solche Kommentare nicht ein, das Quellcodeverwaltungssystem verwaltet diesen Verlauf bereits und ich kann bereits den Verlauf einer Datei protokollieren.
Ich schreibe Kommentare, die beschreiben, warum etwas nicht offensichtliches getan wird. Also, wenn der Bug den Code weniger vorhersehbar und klar macht, dann erkläre ich warum.
Nur wenn die Lösung besonders clever oder schwer zu verstehen war.
Kommentare wie dies sind die Gründe, warum Subversion einen Protokolleintrag bei jedem Commit eingeben kann. Dort solltest du dieses Zeug stecken, nicht in den Code.
Im Laufe der Zeit können diese sich anhäufen und Unordnung hinzufügen. Es ist besser, den Code klar zu machen, irgendwelche Kommentare für verwandte Fehler hinzuzufügen, die nicht offensichtlich sind, und die Fehlerdetails im Tracking-System und im Repository zu behalten.
Während ich dazu tendiere, einige Kommentare zu Bugs im Code bei der Arbeit zu sehen, ist es meine persönliche Vorliebe, einen Code-Commit mit einem Bug zu verknüpfen. Wenn ich eins sage, dann meine ich wirklich einen Fehler. Danach können Sie sich die vorgenommenen Änderungen ansehen und wissen, auf welchen Fehler sie angewendet wurden.
diejenigen lokalisieren Kommentar verfasst wir verwenden DKBUGBUG - die leicht Identität David Kelley fix und Rezensent bedeutet kann, Ofcourse werden wir Datum und andere VSTS Bug-Tracking-Nummer usw. zusammen mit diesem hinzuzufügen.
Ich neige dazu, in der eigentlichen Quelle nicht zu kommentieren, weil es schwierig sein kann, auf dem Laufenden zu bleiben. Allerdings verbinde ich Kommentare in mein Quellcodeverwaltungsprotokoll und Issue Tracker. z.B. Ich könnte etwas in Perforce tun:
[Bug-Id] Problem mit XYZ-Dialog. Verschiebe Größencode zu abc und initialisiere später.
Da ist in meinem issue tracker werde ich etwas tun:
in Änderungsfest 1234.
Verschoben Code abc Sizing und jetzt Initialise später.
Denn dann ist ein guter historischer Marker übrig. Es macht es auch einfach, wenn Sie wissen wollen, warum eine bestimmte Codezeile eine bestimmte Art ist, können Sie einfach den Dateiverlauf betrachten. Sobald Sie die Codezeile gefunden haben, können Sie meinen Commit-Kommentar lesen und deutlich sehen, für welchen Fehler und wie ich ihn behoben habe.
Normalerweise füge ich meinen Namen, meine E-Mail-Adresse und das Datum zusammen mit einer kurzen Beschreibung dessen, was ich geändert habe, weil ich als Berater oft den Code anderer Leute korrigiere.
// Glenn F. Henriksen (<[email protected]) - 2008-09-23
// <Short description>
So wird der Code-Inhaber, oder die Leute nach mir kommen in, herausfinden, was passiert ist, und sie können mit mir in Kontakt treten, wenn sie müssen.
(ja, leider nicht selten haben sie keine Steuerquelle ... für interne Sachen verwende ich TFS Tracking)
Sourcecontrol verfolgt all diese Informationen. Und da Sie ein Berater sind, sollten Sie Ihren Kunden konsultieren, um ein Versionskontrollsystem zu verwenden. –
Ich berate mich, aber manchmal fällt mein Rat auf taube Ohren. Wenn der Client eine Quellcodeverwaltung hat, setze ich diese Kommentare nie ein, dann ist es nur zusätzliches Rauschen. – henriksen
Was ist das Quellcodeverwaltungssystem? –
Nein, ich nicht, und ich hasse es der Code wie dieser Wurf Graffiti haben. Fehlernummern können in der Übergabenachricht an das Versionskontrollsystem und durch Skripts verfolgt werden, um relevante Übermittlungsnachrichten in das Fehlerverfolgungssystem zu übertragen. Ich glaube nicht, dass sie in den Quellcode gehören, wo zukünftige Bearbeitungen die Dinge nur verwirren werden.
Während dies zu dieser Zeit eine gute Idee zu sein scheint, gerät es schnell aus dem Ruder. Solche Informationen können mit einer guten Kombination aus Quellcode-Kontrollsystem und Bug-Tracker besser erfasst werden. Natürlich, wenn etwas schwierig ist, wäre ein Kommentar, der die Situation beschreibt, in jedem Fall hilfreich, aber nicht das Datum, der Name oder die Fehlernummer.
Die Codebasis, an der ich gerade arbeite, ist ungefähr 20 Jahre alt und sie scheinen viele Kommentare hinzugefügt zu haben wie vor einigen Jahren. Zum Glück hörten sie ein paar Jahre auf, nachdem sie in den späten 90ern alles auf CVS umgestellt hatten. Solche Kommentare sind jedoch immer noch im gesamten Code verstreut und die Richtlinie lautet nun "Entferne sie, wenn du direkt an diesem Code arbeitest, aber lasse sie ansonsten". Sie sind oft sehr schwer zu folgen, besonders wenn derselbe Code mehrmals hinzugefügt und entfernt wird (ja, es passiert). Sie enthalten auch nicht das Datum, sondern enthalten die Fehlernummer, die Sie in einem archaischen System suchen müssen, um das Datum zu finden, so dass niemand es tut.
Verdoppeln Sie keine Metadaten, die Ihr VCS für Sie bereithält. Daten und Namen sollten automatisch vom VCS hinzugefügt werden. Ticketnummern, Manager-/Benutzernamen, die die Änderung angefordert haben, usw. sollten VCS-Kommentare enthalten, nicht der Code.
Anstatt dies:
// $ DATE $ NAME $ TICKET // nützlich Kommentar auf die nächste arme Seele
Ich würde dies tun:
// nützlich Kommentar zum nächsten arme Seele
Ich mache es, wenn der Bugfix etwas beinhaltet, das nicht einfach ist, aber meistens, wenn der Bugfix eine lange Erklärung benötigt, nehme ich es als ein Zeichen, dass der Fix nicht gut entworfen wurde. Gelegentlich muss ich um eine öffentliche Schnittstelle 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 kann die Quelle Steuernachricht begehen ist, was ich verwenden, um Annotate die Änderung.
Oft ist ein Kommentar wie dieser verwirrender, da Sie nicht wirklich einen Kontext haben, wie der ursprüngliche Code aussah, oder das ursprüngliche schlechte Verhalten.
Im Allgemeinen, wenn Ihr Bug-Fix nun den Code RICHTIG laufen lässt, einfach lassen Sie es ohne Kommentare. Es besteht keine Notwendigkeit, den korrekten Code zu kommentieren.
Manchmal macht die Fehlerbehebung, dass die Dinge seltsam aussehen, oder der Bugfix testet auf etwas Außergewöhnliches. Dann könnte es angebracht sein, einen Kommentar zu haben - normalerweise sollte sich der Kommentar auf die "Bug-Nummer" aus Ihrer Fehlerdatenbank beziehen.Zum Beispiel könnten Sie einen Kommentar haben, der sagt "Bug 123 - Konto für ungerades Verhalten, wenn der Benutzer in 640 von 480 Bildschirmauflösung ist".
Diese Art der Kommentierung ist äußerst wertvoll in einer Umgebung mit mehreren Entwicklern, in der es eine Reihe von Fähigkeiten und/oder Geschäftswissen über die Entwickler gibt (z. B. - überall).
Für den erfahrenen Entwickler kann der Grund für eine Änderung offensichtlich sein, aber für neuere Entwickler wird dieser Kommentar sie dazu bringen, zweimal nachzudenken und weitere Untersuchungen durchzuführen, bevor sie damit fertig werden. Es hilft ihnen auch, mehr darüber zu erfahren, wie das System funktioniert.
Oh, und eine Notiz aus Erfahrung über die „Ich habe das nur im Quellkontrollsystem“ Kommentare:
Wenn es nicht in der Quelle ist, ist es nicht der Fall war.
ich nicht die Anzahl, wie oft die Quelle der Geschichte für Projekte mit der Source-Control-Software, falsche Verzweigung Modelle usw. verloren wurde aufgrund von Unerfahrenheit zählen Es ist nur einen Ort, der Geschichte ändern 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.
Hier nicht einverstanden. Was passiert, wenn Sie diese Methode umgestalten? Es ist sinnvoll, den Kommentar auch zu löschen. –
Sicher, löschen alten Code und die damit verbundenen Kommentare ist in Ordnung. Es ist der Teil über nur Ihre Kommentare in einem externen System, die sie für Sie verlieren können, während sie noch gültig sind, stimme ich nicht zu. :-) –
Backup. Backup. Backup? – InsertNickHere
Wenn Sie Kommentare wie, dass nach ein paar Jahren fügen Sie den Code der Aufrechterhaltung Sie so viele Bug-Fix haben Kommentare würden Sie den Code nicht lesen können.
Aber wenn Sie etwas ändern, das richtig aussieht (aber einen kleinen Fehler hat), ist es nett, einen kurzen Kommentar hinzuzufügen, der erklärt, was Sie getan haben, damit der nächste Programmierer diesen Code nicht ändert es zurück, weil er (oder sie) denkt, du übertriebene Dinge ohne guten Grund.
Wenn sich der Code auf einer Live-Plattform außerhalb des direkten Zugriffs auf das Quellcodeverwaltungs-Repository befindet, füge ich Kommentare hinzu, um die vorgenommenen Änderungen als Teil des Fixes für einen Fehler im Live-System hervorzuheben.
Andernfalls sollte die Nachricht, die Sie beim Einchecken eingeben, alle Informationen enthalten, die Sie benötigen.
prost,
Rob
Nein, ich Subversion verwenden und immer eine Beschreibung meiner Motivation geben Sie eine Änderung für die Begehung. Ich wiederhole die Lösung normalerweise nicht auf Englisch, stattdessen fasse ich die vorgenommenen Änderungen zusammen.
Ich habe an einer Reihe von Projekten gearbeitet, in denen Kommentare in den Code geschrieben wurden, wenn Fehler behoben wurden. Interessanterweise, und wahrscheinlich nicht zufällig, handelte es sich um Projekte, bei denen entweder kein Quellcode-Kontrollinstrument verwendet wurde oder die beauftragt wurden, diese Art von Konventionen durch das Management zu befolgen.
Ganz ehrlich, ich sehe den Wert in den meisten Situationen nicht wirklich. Wenn ich wissen möchte, was sich geändert hat, schaue ich mir das Subversionsprotokoll und das Diff an.
Nur meine zwei Cent.
Wenn ich Bugfixes/Verbesserungen in Bibliotheken/Komponenten von Drittanbietern mache, mache ich oft einige Kommentare. Dies erleichtert das Auffinden und Verschieben der Änderungen, wenn ich eine neuere Version der Bibliothek/Komponente verwenden muss.
In meinem eigenen Code kommentieren ich selten Bugfixes.
Ich arbeite nicht an Projekten mit mehreren Personen, aber manchmal füge ich einem Komponententest Kommentare zu einem bestimmten Fehler hinzu.
Denken Sie daran, es gibt keine Fehler, nur unzureichende Tests.
Da ich so viel TDD wie möglich mache (alles andere ist sozialer Selbstmord, weil jede andere Methode Sie dazu zwingen wird, endlose Stunden zu arbeiten), behebe ich selten Fehler.
Die meiste Zeit füge ich besondere Bemerkungen wie diese auf den Code:
// 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.
Wenn der Code korrigiert wird, ist der Kommentar nutzlos und für niemanden interessant - nur Lärm.
Wenn der Fehler nicht gelöst ist, ist der Kommentar falsch. Dann macht es Sinn. :) Also lassen Sie solche Kommentare, wenn Sie den Fehler nicht wirklich gelöst haben.
Sie sind völlig richtig. Ich erinnere mich an eine Methode in unserem Code, die nur aus Bug-Fixes zu bestehen scheint (bezüglich der Art der oben erwähnten Kommentare)! –
Was ist ein Tracking-System-Repository? –
Als ich "Tracking-System und Repository" erwähnte, bezog ich mich auf zwei Dinge. Eine, ein Bug-Tracking-System, wie Bugzilla oder JIRA, wo Sie Kommentare zu einem Problem stellen können. Zweitens, ein Quellcode-Repository wie SVN oder Git, wo Sie Kommentare mit Commits setzen können. –