30.07.2009

CSS-Kommentare mit dem "DocBlock"

Sorgfältige Webmaster (ich gehöre nicht zwingend dazu) dokumentieren und kommentieren ihren CSS-Code; zumindest solche Passagen, die eine besondere Bedeutung haben und so auch für einen Außenstehenden nachvollziehbar werden.
Dabei greift man auf die CSS-Kommentar-Schreibweise zurück:

Alles, was sich zwischen den Zeichen /* und */ befindet ist ein CSS-Kommentar, der nur im Quelltext ersichtlich ist, sonst aber keinerlei Wirkung entfaltet.

Das könnte dann zum Beispiel so aussehen:

#content {
color: #666666; /*bewirkt graue Schriftfarbe*/
}

Von CSSDOC wurde dieses System nun verfeinert und dahingehend standardisiert, dass Dokumentationen oder Kommentare innerhalb eines sogenannten "DocBlocks" geschrieben werden. Dadurch sticht die Dokumentation oder der Kommentar besser ins Auge und ist somit auch leichter und schneller als solcher erkennbar.

Ein DocBlock wird durch die Zeichenfolge /** eingeleitet.
Jede Folgezeile innerhalb des Kommentars beginnt mit einem Leerzeichen, gefolgt von einem *   .
Geschlossen wird der Kommentar wie üblich mit (Leerzeichen) */   .

Das Ganze sieht dann z.B. so aus:

/**
* Copyright des CSS-Templates:
* Manuela Musterfrau
* CSS-Gasse 7
* 99999 CSS-Stadt
*/

Oder ihr erläutert eine Spezialangabe, z.B. zwecks Behebung des IE-Doubled-Float-Margin-Bugs. Das könnte dann so aussehen:

#content {
float: left;
margin-left: 150px;
display: inline;
}

/**
* beim IE 6 bewirken "float-left" in Kombination mit "margin-left"
* einen doppelten Abstand, hier also 300px statt wie angegeben 150px.
* Dieser sogenannte "IE-Doubled-Float-Margin-Bug" wird behoben durch
* die Zusatzangabe "display: inline;"
*/

Eine solche Kommentierung sieht doch recht übersichtlich und klar strukturiert aus. Probiert es einfach selbst mal aus. Insbesondere, wenn ihr mit einer Spezialangabe einen besonderen Effekt bewirkt, einen Bug behebt oder - falls ihr "sorgfältige Webmaster" seid - generell zur Dokumentation eurer CSS-Datei.

Aufmerksam wurde ich auf den DocBlock durch einen Artikel von Dirk Jesse bei Webkrauts.

nach oben