Alte TODO-Kommentare im Code erkennen: Automatische Analyse mit todoage

Alte Codebasen sind voller TODO-Kommentare, die niemand mehr ernst nimmt. Doch wer hat sie eigentlich geschrieben und wie lange existieren sie schon? Ohne manuelle Recherche bleibt diese Frage unbeantwortet – bis jetzt.

Mit todoage lassen sich technische Schulden automatisch identifizieren und nach Alter sortieren. Das Tool analysiert Kommentare wie TODO, FIXME oder HACK, führt git blame aus und zeigt übersichtlich an, welche Einträge bereits jahrelang ungelöst sind. So wird aus unsichtbarem Ballast plötzlich handfeste Priorität.

Warum TODO-Kommentare zu technischer Schulden werden

Ein typischer TODO-Kommentar sieht etwa so aus:

// TODO: validate the amount before charging

Doch wann wurde dieser Eintrag hinzugefügt? Von wem? Ohne Kontext bleibt er ein stummer Zeuge vergangener Absichten – und entwickelt sich mit der Zeit zu einem Risiko. Entwickler:innen scheuen sich oft, solche Kommentare anzufassen, aus Angst, ungewollt Fehler zu verursachen. Das Ergebnis: Technische Schulden, die im Verborgenen wachsen.

Mit git blame ließe sich der Ursprung zwar rekonstruieren – doch die manuelle Ausführung ist mühsam. Das neue Tool todoage übernimmt diese Aufgabe und liefert in Sekunden ein strukturiertes Ergebnis, das nach Alter sortiert ist.

Alternativen analysieren: Warum todoage die Lücke füllt

Ähnliche Tools wie tickgit oder todo-tree für Visual Studio Code existieren bereits. Doch sie decken nicht alle Anforderungen ab:

• tickgit (324 Sternchen auf GitHub) versprach einst eine Integration von git blame, wurde aber 2020 ohne diese Funktion eingestellt.
• todo-tree zeigt zwar TODO-Kommentare direkt im Editor an, bietet aber keine CLI-Schnittstelle für CI-Pipelines oder automatisierte Berichte.

todoage kombiniert die Stärken beider Ansätze:

• Altersanalyse: Jeder TODO-Kommentar wird mit Autor und Datum verknüpft.
• CI-Integration: Das Tool kann als Build-Gate fungieren und bei veralteten Einträgen den Build abbrechen.
• Flexible Filterung: Kommentare lassen sich nach Autor, Alter oder Markierung filtern.

Praktische Anwendungen: Von der Analyse zur Automatisierung

Das Tool lässt sich auf verschiedene Weise nutzen. Ein typisches Szenario ist die Integration in Continuous Integration (CI):

npx todoage --max-age 90d --fail-on-stale

Mit diesem Befehl wird der Build nur erfolgreich abgeschlossen, wenn alle TODO-Kommentare jünger als 90 Tage sind. Ältere Einträge werden als stale markiert und blockieren den Prozess. Auch längere Zeiträume sind möglich – etwa --max-age 6m für sechs Monate.

Weitere nützliche Befehle:

• Filterung nach Autor:

todoage --tags FIXME --author alice

• Ausgabe im JSON-Format (z. B. für Dashboards oder Bots):

todoage --json | jq '.items[] | select(.stale)'

Wie todoage zwischen echten Kommentaren und falschen Treffern unterscheidet

Ein häufiges Problem bei TODO-Suchtools sind falsch-positive Treffer. todoage vermeidet dies durch strenge Regeln:

• Nur echte Kommentare: Das Tool erkennt nur Markierungen in Kommentaren, die in Sprachen wie JavaScript (//), Python (#) oder SQL (--) stehen.
• Falsche Treffer ausschließen: Bezeichnungen wie todomvc oder fixme_helper werden ignoriert.
• Case-Sensitivität: Nur großgeschriebene Tags wie TODO oder FIXME werden berücksichtigt.
• Keine Prosa-Treffer: Das Tool durchsucht keine normalen Textpassagen, sondern nur Kommentarblöcke.

Einfache Installation: Node.js und Python

Das Tool steht für beide Ökosysteme zur Verfügung – ohne zusätzliche Abhängigkeiten:

• Node.js-Version:

npx todoage

• Python-Version:

pipx run todoage

Beide Versionen nutzen denselben Kern und erzeugen identische Ausgaben. Entwickler:innen können wählen, welche Laufzeitumgebung auf ihrem System verfügbar ist.

Technische Details: Wie todoage funktioniert

Das Tool besteht aus einem reinen Kern und zwei Laufzeitumgebungen (Node.js und Python). Die wichtigsten Designentscheidungen:

• Reine Funktionen: Funktionen wie scanLine, ageDays und isStale sind ohne Seiteneffekte implementiert – sie nutzen keine externen Ressourcen wie Uhrzeit oder Dateisystem.
• Deterministische Altersberechnung: Die Berechnung basiert auf Millisekunden, die in ganze Tage umgewandelt werden. Das Ergebnis ist zeitzonenunabhängig und reproduzierbar.
• Stateless-Design: Das Tool führt seine Analysen durch und beendet sich wieder. Es schreibt nichts in die Codebasis und benötigt keine Konfigurationsdateien.

Ein Aufruf, der technische Schulden sichtbar macht

Technische Schulden sind oft unsichtbar – bis sie plötzlich zum Problem werden. todoage macht sie greifbar, indem es jahrelang unberührte TODO-Kommentare identifiziert und priorisiert. Das Tool ist besonders wertvoll für:

• Teams, die ihre Codequalität systematisch verbessern wollen.
• Entwickler:innen, die veraltete Kommentare endlich entfernen möchten.
• CI-Pipelines, die technische Schulden automatisch blockieren können.

Probieren Sie es aus und entdecken Sie, welche TODO-Kommentare in Ihrem Code bereits seit Jahren auf ihre Lösung warten. Die Frage ist nicht, ob sie existieren – sondern wie lange sie schon ignoriert werden.