In meinen Bestrebungen einen möglichst sinnvollen Vorschlag zu machen wie man Javadoc/DocBlock nach CSS bringen kann (kurz und neu: CSSDOC getauft) hab ich mir einfach mal die PHPUGFFM Theme gegriffen und umgeschrieben. Und das war so simpel wie mir die Idee nun mal erschienen ist. Und das wiederum ist prima weil man es dann gerne verwendet. Auch ist es eine Datei die von mehreren Autoren erstellt wird. So gesehen schon fast ideale Bedingungen.

CSS Datei vor CSSDOC (8.565 Bytes)| CSS Datei mit CSSDOC (9.691 Bytes)

Wie man an den Dateien im Vergleich sehen kann sieht CSSDOC viel schöner aus und lässt sich besser lesen, vor allem wenn man die Notation von PHP oder Java her kennt. Das ist schon mal der erste Vorteil und beim editieren merkt man direkt dass sich die Datei besser anfassen lässt. Das war aber auch gar nicht anders zu erwarten, die erste praktische Frage war, ob eine Wordpress Theme die Angaben wie Name und Autor in der CSS-Datei ablegt sich so einfach konvertieren lässt. Überraschender Weise war dies gar kein Problem. Schön. Gleichzeitig konnte ich auch mit einer Art Namespace-Konvention für Tags rumspielen die es erlaubt weitere Metadaten abzulegen die Anwendungsspezifisch sind und so in Projekten die Notation erweitern können:

Aber dies nur als Spielerei am Rande, den schließlich liegt es hier am Themesystem von Wordpress, dass es hier bedenkenlos alles frisst. Der weitere Teil des Umbaus der Datei war nicht weiter spektakulär. Einzig durch die genauere Trennung von Datei-DocBlock und Sektions-DocBlock musste man beim Konvertieren der alten Kommentare sich genauer überlegen ob eine neue Sektion erwünscht und wie überhaupt die Datei strukturiert ist. Und dies ging auch sehr gut. Denkt man an manchen Stellen das etwas anders gehört kann dies schnell mit einem @todo Tag angemerkt werden und in Ruhe weitermachen. Am Ende hatte ich die Datei sogar ein gutes Stück weiter aufgeräumt.

Nachdem die Datei soweit fertig konvertiert war, wollte ich ausprobieren welche weiteren konkreten Vorteile solch ein System mir bringen kann. In EditPlus gibt es einige Möglichkeiten um die Arbeit zu vereinfachen, z.B. die Funktionsliste. Gibt man in der CSS-Konfiguration des Editors an, das alle Zeilen mit @section, @todo und @hack eine interessante Position sind, so kann man die mit der Funktionsliste anspringen. Hier ein Screenshot:

Man kann sehr gut sehen wie schnell sowas den Einstieg und die Navigation in der Datei verbessern kann weil nun der Editor festgelegte Muster in der Datei hat, die er herauspicken kann. Ohne CSSDOC musste man sich sowas wenn immer selber ausdenken, hier würde man vom Prozess der Standardisierung profitieren. Auch schön mit den Todo-Einträgen, die nun einfach abgearbeitet werden können oder aber die Hacks – sofern man solche denn braucht. Wenn ich mir das ganze in einer netten Outline in Eclipse vorstelle – warum nicht!

gut war

• Einfach zu machen
• Sieht gut aus
• Lässt sich vom Editor nutzen
• Wordpress findet es auch prima
• Bessere Struktur durch die Sektionen

das ist mir aufgefallen

• Es ist nicht wirklich klar wie man mit @see eindeutig verweisen kann.
• Man sollte klar sagen, das man auch einfache, einzeilige Kommentare nach wie vor verwenden kann und nicht alles in eine Kommentar-Block gesetzt werden muss.
• Hack-Kommentare sind durchaus recht groß. Auch ist fraglich ob es in allen Fällen praktikabel ist, diese nur am Ende einer Sektion zu verwenden. Reicht hier evtl. ein einfaches @hack Tag am Anfang eines kurzen Kommentars aus?
• Die Dateigrösse nimmt ein wenig zu. Dies könnte durch Prozesse/Tools vom Develop-/Staging- ins Livesystem aber behoben werden.

Tags, Tags, Tags

Durch die Arbeit ist aufgefallen das es einige Tag-Ideen aus der Theorie gar nicht braucht: @info und @layout Tags beispielsweise. Diese zusätzlichen Infos können im Docblock bereits ohne Tag abgelegt werden. Sinnvoller ist ein @note Tag um schnell eine Notiz zu hinterlassen. Einfach mal experimentell verwendet wurde das @app-Namespace-Modell. Hier kann ein Sublevel-Name mit @appdef definiert und benannt werden der dann zur freien Verfügung steht. Ebenfalls das @ref Tag mit welchem CSS-Selektoren benannt wurden, kam zum Einsatz. Ist ein bisschen die Ausgeburt des @colordef Tags, welches hier nicht zur Anwendung kam. Hier kurz im Beispiel:

Dies könnte mal wie auch das @ref-Tag helfen einen kleinen Styleguide aus dem CSS für die Frontendentwicklung zu generieren. Vielleicht noch mittels @colorref grassgreen in einem kleinen kommentar?

Meine ersten praktischen Erfahrungen sind erstmal ganz gut. Es bleiben noch viele Fragen offen, schliesslich ist unsere Theme wirklich recht überschaubar. Ich werde mal bald versuchen, eine kleine Anleitung mit den Grundlagen und den ersten Tags zusammenzuschreiben und das ganze ein wenig bekannter machen. Und einfach mehr CSS-Leute fragen, ob sie nicht an den Stylesheets ihrer Projekte mal die CSSDOC Notation ausprobieren wollen. Auch wissen viele CSS-Leute ja noch gar nicht was ein DocBlock ist und was diese Tags sollen. Mal gucken ob ich das eine erste Dokumentation erklären kann. Hier habe ich jedenfalls schonmal ein bunt gemachtes Bild mit Beispielcode:

Wie dem auch sei, dies ist noch ein gutes Stück von einer echten CSSDOC Dokumentation entfernt die sicherlich erstmal nötig sein wird bevor es grössere Kreise zieht.

Der Beitrag wurde am Freitag, den 25. Mai 2007 um 21:22 Uhr veröffentlicht und wurde unter CSS, Home abgelegt. Du kannst die Kommentare zu diesen Eintrag durch den RSS 2.0 Feed verfolgen. Du kannst einen Kommentar schreiben, oder einen Trackback auf deiner Seite einrichten.