03. Dezember 2007
CSS bietet kaum Möglichkeiten, um umfangreichere Anweisungen zu strukturieren. Zwar lassen sich Stylesheets in mehrere Dateien zerlegen oder über die @media Regel gruppieren, aber was war’s dann auch schon.
Für kleinerer Webauftritte, z.B. Weblogs, ist das meist ausreichend. Bei größeren Projekten oder der Verwendung von Content-Management-Systemen verliert man jedoch schnell die Übersicht. Für den produktiven Betrieb kann es durchaus sinnvoll sein, Stylesheets gezielt zu optimieren. Die Entwicklerfassung sollte jedoch immer möglichst gut dokumentiert sein.
CSSDOC – Ein Ansatz für einen Standard
Kein gewissenhafter Programmierer lässt seinen Code undokumentiert. Jenseits des CSS-Tellerrandes existieren daher Lösungen wie Javadoc oder Scriptdoc. Beide Standards verwenden spezielle Kommentare, um Programmcode möglichst effektiv zu dokumentieren bzw. sie ermöglichen die automatische Erstellung von Modul-/Programmdokumentationen. CSSDOC wird von Tom Klingenberg, Timo Derstappen und Dirk Jesse entwickelt und ist ein Ansatz, die Vorteile dieser Lösungen auch für die Arbeit mit CSS nutzbar zu machen.
Grundlagen
Ein Kommentar wird in CSSDOC als DocBlock bezeichnet und folgt einer speziellen Schreibweise. Zu unterscheiden sind dabei DocBlocks für einzelne Abschnitte (section comments) und Dateikommentare (file comments), die den Inhalt einer Datei beschreiben.
Jeder DocBlock wird von der Zeichenkette /** eingeleitet und mit */ beendet. Beide Zeichenketten stehen separat in einer Zeile. Dazwischen befinden sich die eigentlichen Informationen, wodurch das Format für Maschinen lesbar wird.
/**
* Ein einfacher DocBlock
*
* Gelegentlich ist etwas mehr zu sagen. Dann koennen sich
* Kommentare auch schonmal ueber mehrere Zeilen erstrecken.
*/
Das Salz in der Suppe - Tags
Durch spezielle Tags kann der Informationsgehalt eines DocBlocks entscheidend gesteigert werden. Tags können Strukturinformationen, Autoren- und Copyrightinformationen, Information zur Browserkompatibilität usw. enthalten. Ein Tag beginnt immer mit dem Zeichen ‘@’. Beispiel 2 enthält einen Abschnittsbeginn (@section) sowie einen Querverweise (@see).
/**
* @section browser reset
* @see http://www.yaml.de/documentation/...
*
* Reset any browser specific CSS ...
*/
Auch Bugfixes werden durch CSSDOC besser verständlich.
/**
* Doubled Float-Margin Bug
* @see http://...
*
* @bugfix
* @affected IE 5.x/Win, IE6
* @css-for all browsers
* @valid yes
*/
.float_left { float:left; display: inline }
Die Anzahl der Tags ist relativ hoch, daher erfordert ihre Anwendung zweifellos etwas Übung. Du wirst jedoch mit der Zeit feststellen, dass du dank CSSDOC auch nach längeren Bearbeitungspausen schneller Zugang zu Ihrem eigenen oder auch CSS-Code anderer Entwickler finden wirst.
Informationen
Der Beitrag wurde am 3. Dezember 2007 erstmals im Rahmen des Beitragsserie “Adventskalender 2007” bei den Webkrauts veröffentlicht (Direktlink).