Machen TODO-Kommentare Sinn? [geschlossen]

86

Ich arbeite an einem ziemlich großen Projekt und habe die Aufgabe, einige Übersetzungen dafür zu machen. Es gab Unmengen von Etiketten, die nicht übersetzt wurden, und während ich den Code durchsuchte, fand ich dieses kleine Stück Code

//TODO translations

Dies brachte mich dazu, über den Sinn dieser Kommentare für sich selbst (und andere?) Nachzudenken, da ich das Gefühl hatte, dass die meisten Entwickler, nachdem sie einen bestimmten Teil des Codes fertiggestellt haben, das tun, was sie tun sollen, sich das erst dann ansehen, wenn sie es getan haben um es zu pflegen oder neue Funktionen hinzuzufügen. Damit dies TODOfür lange Zeit verloren geht.

Ist es sinnvoll, diese Kommentare zu schreiben, oder sollten sie auf einem Whiteboard / Papier / etwas anderem geschrieben werden, wo sie im Fokus der Entwickler bleiben?

Ivan Crojach Karačić
quelle
2
(einige) IDEs verfolgen diese. Ich benutze sie großzügig, wenn ich die Implementierung eines Moduls nicht vollständig ausgearbeitet habe, aber der Vertrag für mich (oder andere) zufriedenstellend ist, um die Entwicklung an einem anderen verwandten Teil fortzusetzen.
smp7d
3
TODOs sind für mich eher wie "sollte optimieren, aber nicht zu
Jake Berger
8
Wann immer ich an eine Aufgabe denke, die erledigt werden muss, oder an einer Randbedingung, die für die aktuelle Funktion, an der ich arbeite, geprüft werden muss, höre ich auf, was ich schreibe (sogar in der Mitte der Anweisung), und füge ein TODO hinzu (auch wenn) es ist nur die obige Zeile) . Dies hilft zu verhindern, dass diese "Oh ja, ich habe sogar darüber nachgedacht" -Fehler auftreten. Bevor ich die Funktion festschreibe, überprüfe ich die TODOs. Sie werden nie verpflichtet, aber seit ich damit angefangen habe, ist meine Anzahl an Fehlern drastisch gesunken .
BlueRaja - Danny Pflughoeft
8
Ich benutze immer, #warning TODO: …wenn ich das TODO nicht vergessen will.
rechts
2
@WTP: Visual Studio, R #, Netbeans, Eclipse usw. usw. enthalten alle Tools zum Anzeigen aller TODOs innerhalb einer Lösung / eines Arbeitsbereichs. Es gibt keine Notwendigkeit mehr für diesen alten Hack.
BlueRaja - Danny Pflughoeft

Antworten:

107

Ich neige dazu, // todoKommentare für Dinge zu verwenden, die passieren müssen, aber ich kann es nicht sofort tun.

Ich mache auch sicher , dass ich auf sie jagen - ich für sie suchen (Visual Studio hat eine nette Funktion , wo es solche Kommentare für Sie auflistet) und stellen Sie sicher , dass die Dinge sind geschehen.

Aber, wie Sie sagen, sind nicht alle fleißig und wie viele Kommentare neigen sie dazu, im Laufe der Zeit zu verfaulen.

Ich würde sagen, dass dies eher eine persönliche Präferenz ist - solange Sie dokumentieren, was getan werden muss, und danach jagen, spielt es keine Rolle, ob es sich um // todoPostit Notes oder ein Whiteboard handelt (wo sie auch nicht landen können) in Aktion).

Oded
quelle
18
Eclipse hebt sie hervor und konsolidiert eine Liste von ihnen auch für Sie. Und es ist keine schlechte Idee, einen TODO-Kommentar zu schreiben, während Sie über den Gedanken nachdenken, auch wenn Sie nie dazu kommen, ihn tatsächlich zu tun. Eine großmütige Seele kann tatsächlich im Code nach Dingen suchen, die zu tun sind (OSS).
Kochfelder
4
Resharper hat auch eine schöne Liste von TODOs, es funktioniert besser als die Standard-VS-Version (sieht in mehr Dateien aus).
CaffGeek
Ja, angesichts einer Auflistung in Ihrer IDE sind sie hilfreich. Ich würde sagen, dass sie ansonsten von sehr begrenztem Nutzen sind, da die Codebasis enorm sein kann.
Ingenieur
4
Wegen Kommentarfäule datiere und initialisiere ich meine Kommentare immer. Wenn der Kommentar vor drei Jahren von vier Auftragnehmern stammt, können Sie ihn wahrscheinlich löschen.
user1936
2
Da Resharper und Datumsangaben erwähnt wurden, verwende ich eine einfache Resharper-Live-Vorlage von "// TODO $ user $ ($ date $) -"
dark fader
56

Moderne IDEs erkennen die TODOKommentare und sind als solche in ihrem eigenen Bereich / Fenster / Tab sichtbar, so dass sie theoretisch nicht verloren gehen (ich denke, Eclipse und Visual Studio, beide sind mir bekannt genug, um sich daran zu erinnern, dass sie sie erkennen).

Sie können sogar zusätzliche Kommentarwörter wie oder alles andere konfigurieren FIXME, das BEWARESie anpassen möchten. Andere Entwickler in Ihrem Projekt müssen ihre IDE jedoch auf die gleiche Weise anpassen.

Jetzt habe ich "theoretisch" geschrieben, da sich das TODO, obwohl es nicht verloren geht, mehr als oft auf etwas bezieht, das nicht benötigt wird, damit die Anwendung "im Moment" ordnungsgemäß funktioniert. Und "im Moment" kann sich je nach Art / Größe des Projekts über 5 Minuten bis 5 Jahre erstrecken :-)

Meiner Meinung nach ist es immer noch sinnvoller, sie am richtigen Ort im Code zu haben und die Frage "Wo soll ich die Änderung vornehmen?" Genauer zu beantworten als an einer anderen Stelle außerhalb des Codes.

Bearbeiten: Wie im Wikipedia- Artikel zu Kommentaren geschrieben , wird das Datum und der Eigentümer des TODO als eine gute Vorgehensweise angesehen.

Jalayn
quelle
32
Ich denke, das Datum und der Besitzer des TODO ist nur Lärm. Dafür gibt es die Versionskontrolle (und die Schuldfunktion) (wenn Sie die Informationen wirklich brauchen).
Sleske
3
Ich denke nicht, dass eine Wikipedia, die sagt "Es wird geraten", zitierfähig ist. Geruchswarnung. Besserer Link zu dem Artikel, der dies behauptet.
Phresnel
@phresnel Nun, es gibt ein Zitat, das mit diesem "Rat" verbunden ist. Ich hatte nicht das Bedürfnis, dies hier zu wiederholen. Ansonsten stimme ich der Tatsache zu, dass das Zitieren von Wikipedia-Fakten, die nicht durch irgendetwas gestützt sind, gefährlich sein könnte
Jalayn,
@sleske Ich würde eher zustimmen, dass das Rauschen minimal gehalten wird, ABER ich denke, dass IDEs Ihnen diese Informationen aus dem Repository nicht automatisch geben (es sei denn, ich täusche mich, Sie müssten Versionen manuell vergleichen), wenn Sie sie nicht explizit schreiben .
Jalayn
1
Mit der "Annotate" -Funktion von Visual Studio können Sie leicht erkennen, wer die Änderungen an verschiedenen Teilen der Datei, an denen Sie arbeiten, zuletzt eingecheckt hat und von welchem ​​Änderungssatz. Nicht perfekt, aber in vielen Fällen (besonders mit TODOKommentaren) nahe genug, um nützlich zu sein.
ein
13

Es mag einen Sinn ergeben, zumindest benutze ich sie manchmal. Der entscheidende Punkt ist, konsistente Tags wie TODOoder zu verwenden, FIXMEdamit sie mit einer einfachen Textsuche leicht gefunden werden können.

Zum Beispiel sind "quick 'n dirty" -Lösungen praktisch zu etikettieren, etwa:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Wenn der Code das tut, was er tun soll, und sich niemand beschwert, schadet der Kommentar nicht. Wenn Sie Zeit haben, den Code zu verschönern, können Sie einfach nach FIXMEEtiketten suchen .

Joonas Pulakka
quelle
3
"FIXME" und "TODO" haben für mich unterschiedliche Bedeutungen. Eine Übersetzung, ein fest codierter Wert oder ein Ausnahmefehler ex.printStacktrace()sind für mich TODO. Auf der anderen Seite würde FIXME Ausnahmen behandeln, die manchmal auftreten, ein Speicherverlust oder eine andere Art von Fehler, den Sie gefunden, aber nicht vollständig analysiert / behoben haben.
16.
10

In meiner Branche werden Entwickler dazu ermutigt, JIRA-Einträge (oder Ähnliches) zu machen, anstatt Kommentare zu machen, da nicht jeder die Möglichkeit hat, die // todoEinträge zu sehen . Aber manchmal wird in großen Projekten ein benutzerdefiniertes Attribut wie folgt definiert:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

Und dann kann eine Methode auf diese Weise dekoriert werden ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

Und die Höheren können mitkommen und diese automatisch ernten. Für die einfache // todoErinnerung mag es übertrieben sein , aber es ist effektiv. Außerdem ist eine .NET-Plattform erforderlich.

Garry
quelle
5
Ein TODO-Kommentar wird in eine Codezeile umgewandelt. Ein Ticket ist meiner Meinung nach globaler und höherstufiger. Und ich denke, diese Anmerkung ist ein Overkill. TODO hat mehr Möglichkeiten, an mehr Editoren zu arbeiten.
16.
6
Ihre Branche? Welches ist das? Ich kenne keine ganze Branche, die den JIRA-Einsatz fördert ?!
Phresnel
7

TODO ist nur eine Unterform von Kommentaren. Kommentare sind von großem Nutzen, wenn der Verfasser überhaupt weiß, was zu vermitteln ist und wie es zu vermitteln ist. Ein Sinn für Humor kann hier auch in kleinen Dosen angewendet werden, um die Betreuer Jahre später zu erfreuen.

Ich habe letztes Jahr einen Anruf erhalten, dass ein Teil meines Codes in den Ruhestand geht. Ich war ziemlich beeindruckt, dass es seit 16 Jahren in Produktion ist und die Wartung überlebt hat. Seien Sie sich also bewusst, dass Ihr Code eine LANGE Zeit dauern kann. Kommentare zu Absichten, zukünftigen Bedürfnissen usw. können einen großen Beitrag dazu leisten, jemanden zu unterstützen, der zum ersten Mal Ihren Code betrachtet.

Pete Mancini
quelle
1
Wenn es länger als ein Jahrzehnt dort war, war es nicht wirklich nötig und daher ergab das Hinzufügen eines TODOKommentars keinen Sinn.
ein Lebenslauf vom
2
Das setzt voraus, dass sie sich nie ändern. Wie der Code können sich auch Kommentare durch Hinzufügungen, Löschungen und Änderungen ändern. Es ist wahrscheinlicher, dass TODO-Listen auf diese Weise geändert werden. Ich bin mir sicher, dass die Kommentare in den letzten zehn Jahren, seit ich den Code das letzte Mal berührt habe, geändert wurden.
Pete Mancini
6

Nach meiner Erfahrung kommt es darauf an. Der Hauptfaktor ist, ob das Team diszipliniert genug ist, um diesen "kleinen" Kommentaren nachzugehen. Wenn ja, dann machen sie Sinn. Wenn dies nicht der Fall ist, sind diese Kommentare nur Zeitverschwendung, und Sie möchten möglicherweise andere Optionen prüfen, z. B. Story Cards.

Persönlich verwende ich gelegentlich TODO-Kommentare, aber sie sind in der Regel nur von kurzer Dauer und ich habe normalerweise nur eine sehr kleine Anzahl von ihnen wie eins, zwei oder drei. Ich benutze sie mehr als Marker in der Codebasis als alles andere. Wenn ich zu lange warte, um auf sie aufzupassen, vergesse ich, was ich für nötig hielt.

Ich würde es immer vorziehen, diese nicht zu verwenden und stattdessen geeignete Story Cards oder Backlogs oder ähnliches zu verwenden. Verwenden Sie einen Mechanismus für eine Aufgabe.

Manfred
quelle
6

Früher habe ich sie geschrieben, aber ich habe festgestellt, dass Sie sie normalerweise nicht weiterverfolgen.

Deshalb benutze ich sie jetzt nur, um Dinge zu markieren, an denen ich arbeiten möchte, direkt nachdem ich fertig bin, womit ich beschäftigt bin. Ich implementiere beispielsweise eine neue Funktion und stelle fest, dass eine von mir verwendete Funktion einen kleinen Fehler aufweist. Ich erstelle ein FIXME, um dies zu beheben und zu verhindern, dass ich bei meiner aktuellen Aufgabe entgleist.

Um mir zu helfen, sind unsere CI-Builds so eingerichtet, dass sie fehlschlagen, wenn der Code FIXMEs enthält :-).

Wenn Sie potenzielle Probleme bemerken, die nicht sofort behoben werden können, öffnen Sie ein Ticket / einen Fehler / eine Ausgabe für diese. Auf diese Weise können sie wie alle Bugs priorisiert werden. Ich denke, das ist viel besser, als einige Probleme in der Bug-DB und einige im Code als TODOs zu haben.

Optional können Sie dann eine TODO mit der Bug-ID einfügen :-).

sleske
quelle
3

Ich denke, TODOKommentare sind bis zu einem gewissen Grad sinnvoll. Besonders iterativ , wenn Sie arbeiten (wie in agilen und TDD Geschäften üblich ist), gibt es Dinge, die Sie erkennen werden , bevor lange gebraucht werden, aber was Sie nicht wollen , den Umweg machen , dann und dort zu implementieren.

Hässlich wird es, wenn solche Kommentare in der Codebasis verbleiben. Während Sie aktiv an einer Funktion arbeiten, ist es in Ordnung, sie beizubehalten. Sobald Sie sich jedoch dem Abschluss der Funktion nähern, sollten Sie sich darauf konzentrieren, sie loszuwerden. Wenn Sie nicht die Arbeit des tatsächlichen Ersetzens durch richtigen, funktionierenden Code ausführen möchten, sollten Sie zumindest die relevanten Funktionen herausrechnen. @ JoonasPulakkas Beispiel ausleihen, in dem der Code zunächst sagt

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Sie könnten das in so etwas wie ändern

ConnManager.getConnection(GetDatabaseName());

Derzeit ist GetDatabaseName () ein Stub, der einfach denselben String zurückgibt, mit dem Sie begonnen haben. Auf diese Weise gibt es einen klaren Punkt für zukünftige Erweiterungen, und Sie wissen, dass alle Änderungen, die dort vorgenommen werden, überall dort wiedergegeben werden, wo der Datenbankname benötigt wird. Wenn der Datenbankname nur mäßig generisch ist, kann dies die Wartbarkeit massiv verbessern.

Persönlich verwende ich ein eigenes Schlüsselwort anstelle eines strengen Schlüsselworts TODO, obwohl die Absicht dieselbe ist: Um Dinge zu markieren, von denen ich weiß, dass sie erneut überprüft werden müssen. Bevor ich meinen Code einchecke, führe ich eine globale Quellcodesuche nach diesem Schlüsselwort durch, das so ausgewählt wird, dass es normalerweise nirgendwo im Code erscheint. Wenn es gefunden wird, weiß ich, dass ich etwas vergessen habe und kann es reparieren.

Was das Einfügen des Programmierernamens / der Signatur in den Kommentar angeht, halte ich das für übertrieben, wenn Sie ein Versionskontrollsystem für den Quellcode haben (oder?). In diesem Fall werden Sie anhand der Schuldfunktion darüber informiert, wer den Kommentar hinzugefügt hat oder wer zuletzt eine Änderung eingecheckt hat, die den Kommentar berührt hat. In Visual Studio können Sie dies beispielsweise mithilfe der in den Versionsverwaltungsfunktionen enthaltenen Funktion "Annotieren" problemlos durchführen.

ein CVn
quelle
3

Wenn Sie ein TODO oder FIXME schreiben, mit der Idee, dass jemand anderes es reparieren wird, wenn er in einer unbestimmten Zukunft zu diesem Code kommt, würde ich sagen, dass Sie sich nicht darum kümmern. Sie verunreinigen den Code und überladen den Berichtsteil Ihrer IDE, der diese Informationen sammelt.

Um nützlich zu sein, sollten sie eine Möglichkeit bieten, Ihren Code für die (sehr) nahe Zukunft mit einem Lesezeichen zu versehen, damit Sie schneller in den richtigen Geisteszustand zurückkehren können. Mit anderen Worten, Sie platzieren sie nur in Ihrem Code, um sie so schnell wie möglich zu entfernen.

Alles, was länger gelebt wird, sollte in der Tat in der Bug Base platziert werden, wo es hingehört.

Es gibt genug Lärm in unserem Leben, lasst uns keine neue Fanfare von Dingen kreieren, die nach Aufmerksamkeit schreien, während sie woanders benötigt werden.

Meine 2 Cent

Newtopian
quelle
2

Normalerweise mache ich keine // TODO-Kommentare, sondern halte sie alle in einer getrennten Datei. Ich kann immer noch keine Online-Software finden / schreiben, um sie einfach zu verwalten. Daher sind TODO-Dateien für mich nach wie vor am nützlichsten, da ich vergesse, was ich hin und wieder in die TODO-Datei schaue und die Arbeit erledige, wenn ich das Projekt nach kurzer Zeit öffne . Ich habe "filename.cpp 354: Recode this bla bla bla" und es ist viel nützlicher, als // TODO-Kommentar in der Datei zu suchen. Ich habe // TODO earler gemacht, als ich faul war, aber ich entferne nur die alten // TODO-s aus der Quelldatei und repariere sie nicht, wenn das Projekt gut funktioniert. Ich empfehle nachdrücklich, alle // Aufgaben von der Quelle an einen anderen Ort zu verschieben und zusammen mit anderen Aufgaben zu speichern, damit Sie die Aufgaben einfacher priorisieren können. Priorität ist wirklich eine schwierige Sache, wenn Sie alle Ihre Aufgaben in verschiedenen Dateien und verschiedenen Projekten haben.

cnd
quelle
7
Und dann fügen Sie eine neue Funktion in filename.cpp ein, im Fall Ihres Beispiels etwa in Zeile 200, weil Sie es hilfreich finden, einen Teil des Codes umzugestalten. Plötzlich ist Ihr Hinweis bedeutungslos. Ich ziehe die IDE sie aus mir zeigen , wo sie richtig sind jetzt nicht , wo sie waren , als ich die Notwendigkeit sah , TODOwas auch immer.
ein
Ja, Sie haben recht. Manchmal fällt es mir schwer, die Leitung zu finden, aber ich kümmere mich darum. Und ja. Ich kann beides verwenden, um einfach in einer Datei oder einer IDE zu finden, aber um zu wissen, was an einer anderen Stelle zu tun ist.
CND
2

Ich finde es toll, aber nicht alleine. Zum Beispiel:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

Dieser Ansatz funktioniert ziemlich sparsam. Obwohl ich sagen muss, dass es nicht wirklich die professionellste Vorgehensweise ist, Ausnahmen zu machen, um Sie daran zu erinnern, Code zu vervollständigen. Aber es hat mich in einigen Fällen gerettet, in denen Sie denken, Sie hätten etwas abgeschlossen, und sogar aufgeschrieben, dass Sie abgeschlossen haben, wenn Sie es nicht getan haben.

Edward
quelle
2
In diesem Fall können Sie einfach ein werfen, new NotImplementedException()was ein ToDo impliziert.
CodesInChaos
In CI gerne verwenden assert(0 && "TODO[cmaster]: Add click event logic");. Einfach und sehr effektiv beim Erhalten der Nachricht an mich, sollte ich das TODO vergessen ...
cmaster
1

Der große Vorteil von ToDo-Kommentaren gegenüber den anderen Millionen Möglichkeiten, wie eine Aufgabenliste erstellt werden kann, besteht darin, dass ToDo-Kommentare mit dem Code übertragen werden, sodass sie nicht voneinander getrennt werden können.

Wahrscheinlich ist der am besten geeignete Ort für solche Dinge der Issue-Tracker und nicht der Code.

Wyatt Barnett
quelle
0

Ich empfehle dringend, dass jedes TODO oder FIXME in ein offizielles Protokoll eingetragen wird. Ist dies nicht der Fall, können sie leicht durchsucht werden, und es sollte eine Phase in jeder Iteration sein, nach ausstehenden TODOs und FIXMEs zu suchen. Diese können dann katalogisiert und entweder sofort behoben werden, oder das Team kann planen, sie zum geeigneten Zeitpunkt zu reparieren.

Einmal repariert, müssen sie entfernt werden - wenn sie nach der Lösung nicht auf systematische Weise beseitigt werden, verlieren sie ihre Wirksamkeit.

Fazit: Sie sind besser, als überhaupt keine Probleme zu protokollieren, aber Sie müssen sie tatsächlich warten.

Marcin
quelle
-1

IntelliJ benachrichtigt Sie tatsächlich, wenn Sie versuchen, Code mit neuen TODOs festzuschreiben. Sie können ein TODO also immer so interpretieren, als ob "dies wirklich zu dem Zeitpunkt geschehen sollte, zu dem ich einen Commit vornehme".

ripper234
quelle
-1

Wenn Sie das "TODO" als semantisches Etikett für Ihren Kommentar betrachten, sind sie meiner Meinung nach sinnvoll.

In den Codierungsstandards meines Unternehmens legen wir fest, dass die Initialen des verantwortlichen Entwicklers im TODO enthalten sein müssen ( dh , ich würde "SAA TODO:" eingeben). Ich denke, dies ist nützlich, zumindest als Konvention, da es ansonsten die Versuchung gibt, minderwertigen Code mit dem TODO-Hinweis zu belassen, mit dem sich einige zukünftige Entwickler befassen müssen.

Viele IDEs können so konfiguriert werden, dass sie diese Kommentare zu einer Aufgabenliste hinzufügen, sodass sie ähnlich behandelt werden können, um Schriften zu erstellen, und nicht auf unbestimmte Zeit vergessen werden.

Stewart
quelle
-2

Eine widerwärtigere und dennoch effektive Methode ist es wahrscheinlich, Ihre Aufgabenkommentare in Compilermeldungen umzuwandeln, so dass Sie und alle anderen es sehen, wenn das Programm kompiliert wird.

in Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}
Peter Turner
quelle
-4

Nach meiner Erfahrung TODOsollte verwendet werden, um anzuzeigen, dass ein Teil des Codes nicht verwendbar ist, und dem Leser mitzuteilen, was erforderlich ist, um ihn verwendbar zu machen (entweder lokal oder anderswo).

TODOAnmerkungen sollten nicht verwendet werden, um anzuzeigen, dass ein Teil des Codes besser wäre, wenn er auf irgendeine Weise geändert würde. Beispiele hierfür sind schmutziger Code, der besser gewartet werden kann, wenn er umgeschrieben wird, oder eine zusätzliche Funktion, die noch niemand benötigt. Diese Anmerkungen häufen sich und führen zu grep TODOunbrauchbaren Ergebnissen.

Martin Jambon
quelle
Ist das nur deine Meinung oder kannst du es irgendwie bestätigen?
gnat
Dies ist meine Meinung und mein Rat basierend auf meiner Erfahrung. Einige Leute verwenden TODO-Kommentare, um zu sagen: "Ich weiß, wie man guten Code schreibt, aber ich werde es nicht tun, weil es mich nicht interessiert, aber hey, ich habe TODO hier geschrieben, damit es wirklich zeigt, dass ich weiß, wie man sauberen Code schreibt."
Martin Jambon