Ablehnungsbescheid

Diese PEP wurde abgelehnt. Obwohl die Community interessiert sein mag, gibt es keinen Wunsch, die Standardbibliothek an diesen Standard anzupassen.

Zusammenfassung

Diese informative PEP zielt darauf ab, Richtlinien für die konsistente Verwendung von Codetags bereitzustellen, was den Aufbau von Standard-Utilities ermöglichen würde, um die Codetag-Informationen zu nutzen, und den Python-Code über Projekte hinweg einheitlicher macht. Codetags stellen auch ein sehr leichtgewichtiges Programmier-Mikroparadigma dar und werden für Projektmanagement, Dokumentation, Änderungsverfolgung und die Überwachung des Projektzustands nützlich. Dies wird als PEP eingereicht, da seine Ideen als Pythonic gelten, obwohl die Konzepte nicht exklusiv für die Python-Programmierung sind. Hierin werden die Definition von Codetags, die dahinterstehende Philosophie, eine Motivation für standardisierte Konventionen, einige Beispiele, eine Spezifikation, eine Toolset-Beschreibung und mögliche Einwände gegen das Codetag-Projekt/Paradigma aufgeführt.

Diese PEP wird auch als Wiki gepflegt, in dem Leute Kommentare hinzufügen können.

Was sind Codetags?

Programmierer verwenden weithin Ad-hoc-Code-Kommentar-Markup-Konventionen, die als Erinnerung für Codeabschnitte dienen, die genauer geprüft oder überarbeitet werden müssen. Beispiele für Markup sind FIXME, TODO, XXX, BUG, aber es gibt noch viele weitere, die in vorhandener Software weit verbreitet sind. Solches Markup wird fortan als Codetags bezeichnet. Diese Codetags können in Anwendungscode, Unit-Tests, Skripten, allgemeiner Dokumentation oder überall dort auftauchen, wo es angebracht ist.

Codetags werden seit vielen Jahren (Hunderte von Codetags in den Python 2.4 Quellen) an vielen Orten (z. B. c2) diskutiert und verwendet. Weitere historische und aktuelle Informationen finden Sie unter Referenzen.

Philosophie

Wenn Sie die meisten dieser Werte unterstützen, sind Codetags wahrscheinlich nützlich für Sie.

1. So viele Informationen wie möglich sollten im Quellcode (Anwendungscode oder Unit-Tests) enthalten sein. Dies verhindert zusammen mit der Verwendung von Codetags Duplizierung. Die meiste Dokumentation kann aus diesem Quellcode generiert werden; z. B. durch die Verwendung von help2man, man2html, docutils, epydoc/pydoc, ctdoc usw.
2. Informationen sollten fast nie dupliziert werden – sie sollten in einem einzigen Originalformat erfasst werden und alle anderen Orte sollten automatisch aus dem Original generiert oder einfach referenziert werden. Dies ist bekannt als die Single Point Of Truth (SPOT) oder Don’t Repeat Yourself (DRY) Regel.
3. Die Dokumentation, die Kunden erreicht, sollte aus einzelnen Quellen automatisch in alle anderen Ausgabeformate generiert werden. Menschen wünschen sich Dokumentation in vielen Formen. Es ist daher wichtig, ein Dokumentationssystem zu haben, das all diese generieren kann.
4. Die Entwickler sind das Dokumentationsteam. Sie schreiben den Code und sollten den Code am besten kennen. Es sollte kein dediziertes, getrenntes Dokumentationsteam für Projekte geben, die nicht riesig sind.
5. Klartext (mit nicht-invasiver Auszeichnung) ist das beste Format zum Schreiben von allem. Alle anderen Formate müssen aus dem Klartext generiert werden.

Das Design von Codetags wurde von folgenden Zielen beeinflusst

1. Kommentare sollten so kurz wie möglich sein.
2. Codetag-Felder sollten optional und von minimaler Länge sein. Standardwerte und benutzerdefinierte Felder können von einzelnen Code-Shops festgelegt werden.
3. Codetags sollten minimalistisch sein. Je schneller etwas notiert werden kann, desto wahrscheinlicher wird es notiert.
4. Die häufigste Verwendung von Codetags wird nur null bis zwei Felder aufweisen, und diese sollten am einfachsten einzugeben und zu lesen sein.

Motivation

• Verschiedene Produktivitätstools können rund um Codetags erstellt werden.

  Siehe Werkzeuge.

• Fördert Konsistenz.

  Historisch gesehen wurde eine Teilmenge dieser Codetags informell im Großteil des vorhandenen Quellcodes verwendet, sei es in Python oder in anderen Sprachen. Tags wurden inkonsistent mit unterschiedlichen Schreibweisen, Semantik, Format und Platzierung verwendet. Zum Beispiel könnten einige Programmierer Datumsstempel und/oder Benutzerkennungen einschließen, auf eine einzige Zeile beschränken oder nicht, den Codetag anders als andere schreiben usw.

• Fördert die Einhaltung des SPOT/DRY-Prinzips.

  z. B. eine Roadmap dynamisch aus Codetags generieren, anstatt TODOs mit einem separaten Roadmap-Dokument synchron zu halten.

• Leicht zu merken.

  Alle Codetags müssen prägnant, intuitiv und semantisch nicht überlappend sein. Das Format muss ebenfalls einfach sein.

• Verwendung nicht erforderlich/aufgezwungen.

  Wenn Sie noch keine Codetags verwenden, besteht keine Verpflichtung, damit zu beginnen, und kein Risiko, den Code zu beeinflussen (aber siehe Einwände). Eine kleine Teilmenge kann übernommen werden und die Werkzeuge sind trotzdem nützlich (einige Codetags wurden wahrscheinlich bereits ad hoc übernommen). Außerdem ist es sehr einfach, einen Codetag zu identifizieren und zu entfernen (und möglicherweise aufzuzeichnen), der nicht mehr als nützlich erachtet wird.

• Bietet einen globalen Überblick über den Code.

  Werkzeuge können zur Generierung von Dokumentation und Berichten verwendet werden.

• Ein logischer Ort zur Erfassung von CRCs/Stories/Anforderungen.

  Die XP-Community erfasst Stories oft nicht elektronisch, aber Codetags scheinen ein guter Ort zu sein, um sie zu platzieren.

• Extrem leichtgewichtiger Prozess.

  Das Erstellen von Tickets in einem Tracking-System für jeden Gedanken verlangsamt die Entwicklungsgeschwindigkeit. Selbst wenn ein Ticketing-System verwendet wird, sind Codetags nützlich, um einfach Links zu diesen Tickets zu enthalten.

Beispiele

Dies zeigt einen einfachen Codetag, wie er allgemein im Quellcode vorkommt (mit der Ergänzung eines nachgestellten <>)

# FIXME: Seems like this loop should be finite. <>
while True: ...

Das folgende konstruierte Beispiel demonstriert eine typische Verwendung von Codetags. Es verwendet einige der verfügbaren Felder, um die Zuweisungsempfänger (ein Paar von Programmierern mit den Initialen MDE und CLE), das Datum der erwarteten Fertigstellung (Woche 14) und die Priorität des Elements (2) anzugeben.

# FIXME: Seems like this loop should be finite. <MDE,CLE d:14w p:2>
while True: ...

Dieser Codetag zeigt einen Fehler mit Feldern, die Autor, Entdeckungsdatum (Ursprung), Fälligkeitsdatum und Priorität beschreiben.

# BUG: Crashes if run on Sundays.
# <MDE 2005-09-04 d:14w p:2>
if day == 'Sunday': ...

Hier ist eine Demonstration, wie man Codetags nicht verwendet. Dies hat viele Probleme: 1) Codetags können keine Zeile mit Code teilen; 2) Fehlender Doppelpunkt nach der Mnemotechnik; 3) Ein Codetag, der sich auf Codetags bezieht, ist normalerweise nutzlos und schlimmer noch, er ist nicht abschließbar; 4) Es besteht kein Bedarf für viele Felder für einen trivialen Codetag; 5) Felder mit unbekannten Werten (t:XXX) sollten nicht verwendet werden.

i = i + 1   # TODO Add some more codetags.
# <JRNewbie 2005-04-03 d:2005-09-03 t:XXX d:14w p:0 s:inprogress>

Spezifikation

Dies beschreibt das Format: Syntax, mnemotechnische Namen, Felder und Semantik sowie die separate ERLEDIGT-Datei.

# MNEMONIC: Some (maybe multi-line) commentary. <field field ...>

# TODO: Recurse into subdirs only on blue
# moons. <MDE 2003-09-26>
[2005-09-26 Oops, I underestimated this one a bit.  Should have
used Warsaw's First Law!]

# FIXME: ...
...

Werkzeuge

Derzeit verwenden Programmierer (und manchmal Analysten) typischerweise grep, um eine Liste von Elementen zu generieren, die einem einzelnen Codetag entsprechen. Verschiedene hypothetische Produktivitätstools könnten jedoch von einem konsistenten Codetag-Format profitieren. Einige Beispielwerkzeuge folgen.

Dokumentengenerator

Mögliche Dokumente: Glossar, Roadmap, Manpages

Codetag-Historie

Verfolgen (mit Schnittstelle zum Versionskontrollsystem), wann ein BUG-Tag (oder ein beliebiger Codetag) in einem Codeabschnitt entstanden/behoben wurde.

Code-Statistiken

Ein Projekt-Health-O-Meter

Codetag Lint

Benachrichtigung über ungültige Verwendung von Codetags und Unterstützung bei der Portierung zu Codetags.

Story Manager/Browser

Ein elektronisches Mittel, um XP-Notizkarten zu ersetzen. In MVC-Begriffen ist der Codetag das Modell, und der Story Manager könnte ein grafischer Viewer/Controller sein, um visuelle Neuordnung, Priorisierung und Zuweisung sowie Meilensteinverwaltung durchzuführen.

Jeder Texteditor

Wird zum Ändern, Entfernen, Hinzufügen, Neuordnen und Aufzeichnen von Codetags verwendet.

Es gibt bereits einige existierende Tools, die eine kleinere Menge von Pseudo-Codetags nutzen (siehe Referenzen). Es gibt auch eine beispielhafte Codetags-Implementierung in Arbeit, bekannt als das Codetag-Projekt.

Einwände

Einwand:

Extreme Programming argumentiert, dass solche Codetags niemals im Code existieren sollten, da der Code die Dokumentation ist.

Verteidigung:

Vielleicht sollten Sie die Codetags stattdessen in den Unit-Test-Dateien platzieren. Außerdem ist es schwierig, Dokumentation aus nicht kommentiertem Quellcode zu generieren.

Einwand:

Zu viel vorhandener Code hat die vorgeschlagenen Richtlinien nicht befolgt.

Verteidigung:

[Einfache] Dienstprogramme (ctlint) könnten existierenden Code konvertieren.

Einwand:

Verursacht Duplizierung mit dem Tracking-System.

Verteidigung:

Nicht wirklich, es sei denn, die Felder werden missbraucht. Wenn ein Element im Tracker vorhanden ist, reicht eine einfache Ticketnummer im Codetag-Trackerfeld aus. Vielleicht wäre ein duplizierter Titel akzeptabel. Außerdem ist es zu mühsam, für jeden Punkt, der einem Entwickler auf die Schnelle einfällt, ein Ticket zu erstellen. Darüber hinaus könnte das Tracking-System für einfache oder kleine Projekte, die die relevanten Daten angemessen in einem Codetag unterbringen können, möglicherweise entfallen.

Einwand:

Codetags sind hässlich und vermüllen den Code.

Verteidigung:

Das ist ein guter Punkt. Aber ich hätte diese Information lieber an einem Ort (dem Quellcode) als in verschiedenen anderen Dokumenten, die wahrscheinlich dupliziert oder vergessen werden. Die abgeschlossenen Codetags können in die ERLEDIGT-Datei oder in den Papierkorb verschoben werden.

Einwand:

Codetags (und alle Kommentare) werden veraltet.

Verteidigung:

Nicht so sehr, wenn andere Quellen (extern sichtbare Dokumentation) von ihrer Richtigkeit abhängen.

Einwand:

Codetags haben selten geschätzte Fertigstellungstermine jeglicher Art. OK, die Felder sind optional, aber Sie möchten Felder vorschlagen, die tatsächlich weit verbreitet sein werden.

Verteidigung:

Wenn ein Element nicht schätzbar ist, geben Sie kein Datumsfeld an. Mit Werkzeugen, die Elemente nach Fälligkeitsdatum und/oder Priorität nach Ordnung und/oder Farbe anzeigen, ist es einfacher, Schätzungen vorzunehmen. Wenn Ihre Roadmap eine dynamische Reflexion Ihrer Codetags ist, ist es viel wahrscheinlicher, dass Sie die Codetags korrekt halten.

Einwand:

Benannte Variablen für die Feldparameter in den <> sollten anstelle von kryptischen Ein-Buchstaben-Präfixen verwendet werden. D. h. <MDE p:3> sollte eher <author=MDE, priority=3> sein.

Verteidigung:

Es ist einfach zu viel Tippen/Umständlichkeit, Felder auszuschreiben. Ich argumentiere, dass p:3 i:2 genauso gut lesbar ist wie priority=3, iteration=2 und es ist viel wahrscheinlicher, dass es getippt und erinnert wird (siehe Punkt C in Philosophie). In diesem Fall übertrifft Praktikabilität die Reinheit. Es gibt nicht viele Felder zu verfolgen, daher sind Ein-Buchstaben-Präfixe geeignet.

Einwand:

Synonyme sollten veraltet werden, da es besser ist, nur eine Möglichkeit zu haben, etwas zu schreiben.

Verteidigung:

Viele Programmierer bevorzugen kurze mnemotechnische Namen, besonders in Kommentaren. Deshalb wurden kurze Mnemotechniken als primäre Namen gewählt. Andere sind jedoch der Meinung, dass eine explizite Schreibweise weniger verwirrend und weniger fehleranfällig ist. Es wird immer zwei Lager zu diesem Thema geben. Daher sollten Synonyme (und vollständige, ausgeschriebene Schreibweisen) weiterhin unterstützt werden.

Einwand:

Es ist grausam, undurchsichtige Akronyme und Abkürzungen zu verwenden (für Mnemotechniken), die Vokale weglassen; es ist schwer, diese herauszufinden. Aus diesem Grund hasse ich: MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ, FTR WKRD RVDBY

Verteidigung:

Mnemotechniken werden bevorzugt, da sie recht einfach zu merken sind und weniger Platz einnehmen. Wenn Programmierer keine Vokale weglassen würden, könnten wir nur sehr wenig Code auf eine Zeile bringen. Der Platz ist wichtig für diejenigen, die Kommentare schreiben, die oft auf eine einzige Zeile passen. Aber bei der universellen Verwendung einer Kanone ist es viel unwahrscheinlicher, etwas auf eine Zeile zu bekommen.

Einwand:

Es dauert zu lange, die Felder einzugeben.

Verteidigung:

Dann verwenden Sie sie (die meisten oder keine von ihnen) nicht, besonders wenn Sie der einzige Programmierer sind. Das Beenden eines Codetags mit <> ist eine kleine Mühe, und damit ermöglichen Sie die Nutzung der vorgeschlagenen Werkzeuge. Editor-Autovervollständigung von Codetags ist ebenfalls nützlich: Sie können Ihren Editor programmieren, um eine Vorlage zu stempeln (z. B. # FIXME . <MDE {date}>) mit nur einem oder zwei Tastendrücken.

Einwand:

Arbeitswoche ist eine obskure und unübliche Zeiteinheit.

Verteidigung:

Das stimmt, aber es ist eine sehr geeignete Granularitätseinheit für Schätzungs-/Zielzwecke und ist sehr kompakt. Der ISO 8601 ist weithin verstanden, erlaubt aber nur die Angabe eines bestimmten Tages (restriktiv) oder Monats (breit).

Einwand:

Ich lehne es ästhetisch ab, dass der Kommentar im Fall eines leeren Feldes mit <> beendet wird.

Verteidigung:

Es ist notwendig, einen Abschluss zu haben, da Codetags von Nicht-Codetag-Kommentaren gefolgt werden können. Oder Codetags könnten auf eine einzige Zeile beschränkt werden, aber das ist prohibitiv. Mir fällt kein einzelnes Zeichen als Abschluss ein, das angemessen und signifikant besser als <> ist. Vielleicht könnte @ ein Abschluss sein, aber dann werden die meisten Codetags ein unnötiges @ haben.

Einwand:

Ich kann keine Codetags verwenden, wenn ich HTML schreibe, oder weniger spezifisch, XML. Vielleicht wäre @fields@ besser als <fields> als Trennzeichen.

Verteidigung:

Vielleicht haben Sie Recht, aber <> sieht besser aus, wenn anwendbar. XML/SGML könnten @ verwenden, während gängigere Programmiersprachen bei <> bleiben.

Referenzen

Einige andere Werkzeuge haben sich der Definition/Ausnutzung von Codetags genähert. Siehe http://tracos.org/codetag/wiki/Links.