Montag,
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

Struktureller Aufbau einer CSS-Datei

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).


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.

Dieser Eintrag kann nicht mehr kommentiert werden.