Machen TODO-Kommentare Sinn? [geschlossen]

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?

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

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.

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 .

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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".

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.

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'}

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.