Eigene TODO-Muster in PhpStorm projektweit konfigurieren

1. TODO-Kommentare als Arbeitswerkzeug statt blosse Notiz

In vielen Projekten sind TODO-Kommentare kaum mehr als eine persoenliche Gedaechtnisstuetze, die im Code verstreut liegt und nie wieder systematisch angeschaut wird. Dabei bietet PhpStorm mit dem TODO Tool Window ein vollstaendiges System, um solche Markierungen projektweit zu sammeln, zu filtern und gezielt abzuarbeiten. Der Schluessel dazu liegt darin, ueber das Standardpaar TODO und FIXME hinauszugehen und eigene, semantisch klare Pattern zu definieren.

Ein Pattern wie MAGENTO-UPGRADE: signalisiert sofort, worum es geht, waehrend ein generisches TODO: erst gelesen werden muss, um die Kategorie zu erkennen. Bei einer Codebasis mit mehreren hundert TODO-Kommentaren macht dieser Unterschied den entscheidenden Unterschied zwischen einem durchsuchbaren Aufgabenkatalog und einer unstrukturierten Ansammlung von Notizen, die niemand mehr priorisieren kann.

2. Wie das Standard-System TODO und FIXME funktioniert

PhpStorm erkennt TODO und FIXME standardmaessig in allen unterstuetzten Dateitypen, ohne dass eine Konfiguration noetig ist. Jeder Kommentar, der mit einem dieser Schluesselwoerter beginnt, erscheint automatisch im TODO Tool Window, erreichbar ueber View, Tool Windows, TODO oder das entsprechende Icon am unteren Rand des Editors. Die Erkennung basiert auf regulaeren Ausdruecken, die unter Settings, Editor, TODO einsehbar und veraenderbar sind.

FIXME wird standardmaessig mit hoeherer Prioritaet dargestellt als TODO, sichtbar an einem roten statt gelben Icon im Tool Window. Diese Priorisierung lohnt sich auch fuer eigene Pattern, denn sie erlaubt eine grobe Sortierung nach Dringlichkeit, bevor ueberhaupt inhaltlich nach Kategorie gefiltert wird. Wer die Standardmuster versteht, kann eigene Pattern nach demselben Prinzip aufbauen und in dieselbe Prioritaetslogik einordnen.

3. Eigene Pattern definieren: Syntax und Beispiele

Unter Settings, Editor, TODO laesst sich ueber das Plus-Symbol ein neues Pattern anlegen. Die Konfiguration besteht aus einem regulaeren Ausdruck, einer Farbe und einer Icon-Zuordnung. Fuer ein Pattern wie MAGENTO-UPGRADE: eignet sich ein einfacher Ausdruck, der case-insensitive nach dem Woreingang sucht und optional den Text nach dem Doppelpunkt als Beschreibung erfasst, damit dieser im Tool Window direkt lesbar ist.

Sinnvolle Kategorien fuer eine Magento-Codebasis sind neben MAGENTO-UPGRADE auch SECURITY: fuer sicherheitsrelevante Stellen, PERF: fuer bekannte Performance-Schulden und REFACTOR: fuer Code, der funktioniert, aber strukturell verbessert werden sollte. Wichtig ist, die Pattern-Liste bewusst klein zu halten, denn mit jeder zusaetzlichen Kategorie steigt der Aufwand, sie im Team konsistent zu verwenden und nicht wieder auf das generische TODO zurueckzufallen.

Settings > Editor > TODO > + (Pattern hinzufuegen)
Pattern:  \bMAGENTO-UPGRADE:.*
Case sensitive: nein
Icon: eigenes Icon/Farbe waehlen, z.B. Orange

Beispiel im Code:
// MAGENTO-UPGRADE: Prueft PHP 8.4 Kompatibilitaet fuer array_key_first Nutzung

4. Icon und Farbe pro Pattern fuer schnelle Unterscheidung

Jedes Pattern in PhpStorm kann eine eigene Kombination aus Icon und Farbe erhalten, sichtbar sowohl direkt im Editor am linken Rand als auch im TODO Tool Window. Diese visuelle Unterscheidung ist besonders wertvoll, wenn mehrere Kategorien im selben Modul vorkommen: Ein orangenes Symbol fuer MAGENTO-UPGRADE neben einem roten fuer SECURITY erlaubt es, beim schnellen Scrollen durch eine Datei sofort zu erkennen, welche Art von Aufgabe an welcher Stelle wartet.

Die Farbwahl sollte sich an bestehenden Konventionen orientieren, etwa Rot fuer sicherheitskritische und dringende Punkte, Orange fuer geplante, aber noch nicht terminierte Arbeiten und Blau fuer rein informative Hinweise ohne unmittelbaren Handlungsbedarf. Diese Konsistenz reduziert die Einarbeitungszeit fuer neue Teammitglieder, weil die Bedeutung eines Markers bereits ueber die Farbe erschliessbar ist, bevor der Text ueberhaupt gelesen wird.

5. TODO Tool Window: Gruppierung nach Pattern statt nach Datei

Das TODO Tool Window bietet standardmaessig eine Gruppierung nach Datei, was bei einer grossen Codebasis schnell unuebersichtlich wird, weil verwandte Aufgaben ueber viele Dateien verstreut erscheinen. Ueber das Filter-Icon im Tool Window laesst sich stattdessen auf eine flache Liste oder eine Gruppierung nach Modul umschalten, kombiniert mit der Moeglichkeit, gezielt nach einem einzelnen Pattern zu filtern, etwa nur MAGENTO-UPGRADE-Eintraege anzuzeigen.

In der Praxis bedeutet das: Statt eine Datei nach der anderen zu oeffnen und zu pruefen, ob dort TODO-Kommentare liegen, filtert man das Tool Window einmal auf ein Pattern und erhaelt eine vollstaendige, projektweite Liste genau dieser Kategorie. Bei einem PHP-Versions-Upgrade laesst sich so in wenigen Sekunden feststellen, wie viele MAGENTO-UPGRADE-Stellen im gesamten Projekt noch offen sind, unabhaengig davon, in welchem Modul sie liegen.

TODO Tool Window (View > Tool Windows > TODO)
  Filter-Icon -> "Group by" -> Module statt Datei
  Filter-Icon -> Pattern-Checkbox -> nur "MAGENTO-UPGRADE" aktiv lassen
  Ergebnis: flache, projektweite Liste aller offenen MAGENTO-UPGRADE Stellen

6. Projektweite gegenueber globaler Konfiguration

PhpStorm unterscheidet zwischen IDE-weiten TODO-Pattern, die fuer alle Projekte auf dem eigenen Rechner gelten, und projektspezifischen Pattern, die in der Projektkonfiguration gespeichert werden. Fuer Teamprojekte ist Letzteres der richtige Weg: Die Pattern-Definitionen landen dann in einer Konfigurationsdatei innerhalb des .idea-Ordners und koennen versioniert werden, sodass jedes Teammitglied automatisch dieselben Kategorien sieht, sobald es das Projekt oeffnet.

Ein haeufiger Fehler ist, Pattern nur lokal in den eigenen IDE-Settings anzulegen. Dann funktioniert die Erkennung zwar fuer die eine Person, aber Kollegen sehen im selben Code lediglich unformatierten Text ohne Icon und ohne Eintrag im Tool Window. Vor der teamweiten Einfuehrung eines neuen Patterns lohnt sich daher ein kurzer Test, ob die Konfigurationsdatei tatsaechlich im Repository landet und nicht versehentlich in der global ignorierten Nutzerkonfiguration verbleibt.

7. Praxisbeispiel: MAGENTO-UPGRADE als Migrationswerkzeug

Beim Wechsel auf eine neue Magento- oder PHP-Version ist es ueblich, dass waehrend der laufenden Entwicklung bereits bekannte Stolperstellen markiert werden, lange bevor das eigentliche Upgrade ansteht. Ein Kommentar wie MAGENTO-UPGRADE: readonly Properties fuer PHP 8.2 Kompatibilitaet pruefen dokumentiert das Wissen genau an der betroffenen Stelle, statt es in einem separaten Ticket-System zu verwalten, das schnell aus dem Blick geraet.

Steht das Upgrade dann tatsaechlich an, filtert das Team das TODO Tool Window auf das Pattern MAGENTO-UPGRADE und erhaelt eine vollstaendige, code-nahe Checkliste. Jeder Eintrag laesst sich per Doppelklick direkt an der betroffenen Stelle oeffnen, wodurch der Kontext sofort sichtbar ist, ohne erst ein externes Ticket lesen zu muessen. Nach Abschluss des Upgrades werden die erledigten Kommentare entfernt, wodurch das Pattern automatisch wieder leer wird und fuer die naechste Migration bereitsteht.

8. Kombination mit Scopes und weiteren Filtern

Das TODO Tool Window laesst sich zusaetzlich mit PhpStorm-Scopes kombinieren, also benutzerdefinierten Dateimengen, die etwa nur ein bestimmtes Modul oder ausschliesslich PHP-Dateien umfassen. Ueber das Scope-Dropdown im Tool Window laesst sich die Anzeige auf einen definierten Bereich einschraenken, was besonders bei sehr grossen Monorepos mit vielen Modulen hilfreich ist, in denen sonst tausende Eintraege gleichzeitig angezeigt wuerden.

In Kombination mit Pattern-Filterung ergibt sich so eine zweistufige Eingrenzung: zuerst der Scope auf ein bestimmtes Modul, danach das Pattern auf eine bestimmte Kategorie. Fuer ein Team, das etwa nur die Checkout-relevanten Module vor einem Release pruefen moechte, laesst sich damit in Sekunden eine praezise Liste erzeugen, statt manuell durch das gesamte Projekt zu suchen.

9. Grenzen, Fallstricke und Vergleich der Pattern-Typen

So nuetzlich eigene Pattern sind, sie ersetzen kein vollwertiges Ticket-System fuer komplexe, mehrstufige Aufgaben. Sinnvoll sind sie vor allem fuer lokal begrenzte, code-nahe Hinweise, die im Kontext der jeweiligen Zeile verstaendlich sind. Fuer groessere Vorhaben mit mehreren Beteiligten und Abhaengigkeiten bleibt ein externes Tracking-System weiterhin die bessere Wahl, waehrend TODO-Pattern die Bruecke zwischen Ticket und konkretem Code schlagen.

Ein weiterer Fallstrick ist die schleichende Unordnung: Ohne regelmaessige Pflege sammeln sich veraltete Eintraege an, die laengst erledigt sind, aber im Code stehen bleiben. Ein kurzer Check des TODO Tool Windows vor jedem Release, gefiltert nach den wichtigsten Pattern, verhindert, dass die Liste zu einem ungefilterten Datenfriedhof wird, in dem echte Prioritaeten nicht mehr erkennbar sind.

10. Zusammenfassung

11. FAQ: TODO-Muster in PhpStorm: Das Wichtigste auf einen Blick