Webkrauts Logo

Webkrauts Webkrauts Schriftzug

- für mehr Qualität im Web

Stylesheets kommentieren mit CSSDOC

Wir haben noch nicht alle älteren Artikel nachbearbeitet. Das bezieht sich in der Regel nur auf die Codebeispiele, die noch nicht optimal dargestellt werden.

Stylesheets kommentieren mit CSSDOC

Dirk Jesse erklärt in diesem Kurzbeitrag, wie man Stylesheets mittels CSSDOC verständlich kommentiert und so eine Basis auch für das Arbeiten im Team legen kann.

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

Struktureller Aufbau einer CSS-DateiEin 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  können sich
   * Kommentare auch schonmal über 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  declaration to known values
   */

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.

Kommentare

Webstandard-Team
am 03.12.2007 - 08:39

Kommentare bezüglich CSS-Struktur, ok. Aber Kommentare bezüglich Bugfixes? Diese sollten diejenigen die an Projekten arbeiten doch kennen, oder? Ansonsten wird die Pflege einer solchen Datei und diese selbst auch, sicherlich größer und nicht mehr unbedingt übersichtlicher, wenn man dabei an die zahlreichen Bufixes denkt. Für das gezielte Kommentieren von Änderungen bzw. Neuerungen in Sachen CSS bevorzuge ich eher den Einsatz von Versionskontrollsoftware wie CVS oder Subversion. Somit sind Kommentare bezüglich eventueller Änderungen des CSS-Code nicht mehr nötig.

Permanenter Link

Marc
am 03.12.2007 - 09:29

Ähm, Bugfix im Sinne von Beheben von Browserbugs. So habe ich das zumindest verstanden.

Permanenter Link

Dirk
am 03.12.2007 - 09:30

Aber Kommentare bezüglich Bugfixes? Diese sollten diejenigen die an Projekten arbeiten doch kennen, oder?

Gerade das Kommentieren von Bugfixes hat sich nach meinen Erfahrungen als wichtig und durchaus sinnvoll erwiesen. Wenn es darum geht, verschiedene IE-Versionen unterschiedlich zu behandeln, sehen beileibe nicht alle Fixes so übersichtlich aus wie das im Artikel beschriebene Beispiel (Stichwort: Verwendung von Parser-Bugs).

Eine Versionskontrollsoftware ist ebenso sinnvoll, ersetzt aber nicht das Kommentieren des eigenen Codes, wenn dieser auf Dauer oder auch für Dritte verständlich bleiben soll.

Permanenter Link

Webstandard-Team
am 03.12.2007 - 09:41

Keine Frage Dirk, kommentieren ist wichtig und sie sollen auch nicht von Versionskontrollsoftware abgelöst werden. Durch nützliche Kommentare haben auch andere, neue oder auch externe Mitarbeiter die bspw. an einem umfangreichen Projekt arbeiten, die Möglichkeit den Aufbau besser verstehen zu können. Aber wozu Bugfixes kommentieren? Derjenige der bspw. an einem umfangreichen und großen Projekt arbeitet sollte sich damit auskennen. Du weißt, dass es nicht gerade wenig Bugfixes gibt. Idealerweise sollten bspw. IE spezifische CSS-Eigenschaften via Conditional Comments angeboten werden.

Permanenter Link

Eric Eggert
am 03.12.2007 - 09:46

Idealerweise sollten bspw. IE spezifische CSS-Eigenschaften via Conditional Comments angeboten werden.

Du weißt aber schon, dass es da unterschiedliche Ideale gibt, oder?

Permanenter Link

Webstandard-Team
am 03.12.2007 - 09:53

Aber sicher ;o)

Permanenter Link

Dirk
am 03.12.2007 - 09:55

Du weißt, dass es nicht gerade wenig Bugfixes gibt. Idealerweise sollten bspw. IE spezifische CSS-Eigenschaften via Conditional Comments angeboten werden.

Ein Beispiel: Wirf mal einen Blick in die Datei 'iehacks.css' aus dem YAML-Framework. Diese enthält ausschließlich Bugfixes für den Internet Explorer (5.0 - 7.0), die über einen Conditional Comment eingebunden werden. Sicherlich enthält die Datei ein paar mehr Bugfixes, als in einem 0-8-15 Layout erforderlich werden. Aber stell Dir vor, die Kommentare würden fehlen. Wie behält man als Entwickler (der ein Projekt erstellt, abschließt und sich dem nächsten zuwendet) auf Dauer den Überblick, welche Eigenschaft als Flicken wofür notwendig war? Zum Teil ergeben sich sogar Überschneidungen vom Stile: Bugfix kontra Javscript-Effekte. Pflegt man Projekte über Jahre, ist einmal getroffene Entscheidungen - gut dokumentiert - gelegentlich eine gute Warnung gegen vorschnelle Änderungen.

CSSDOC ist ein Vorschlag, keine Zwang. Mir hat die Art und Weise der Kommentierung sehr viel gebracht und ich denke, dass dieser Weg bei größeren Projekten (nicht nur bei YAML) durchaus sinnvoll ist.

Permanenter Link

Webstandard-Team
am 03.12.2007 - 10:18

Das CSSDOC ein Vorschlag und kein Zwang ist, versteht sich doch von selbst. Das steht vollkommen außer Frage. Die von dir angesprochene CSS-Datei ist vorbildlich dokumentiert und kommentiert, so das jeder der mit YAML beginnt oder es einsetzen will dies versteht. Bei denjenigen die professionell diese Arbeiten machen, kann bzw. sollte man diese Kenntnisse darüber voraussetzen. Oder nicht? Und wie die iehacks.css (11KB) verdeutlicht ist sie ohne Kommentare mit 2KB wesentlich kleiner. Zusammenfassend ist zu sagen, dass CSSDOC eine gute Idee ist, nur sollte eine Dokumentation nur dann eingesetzt werden, wenn sie auch wirklich nötig ist und nicht alle Eventualitäten abdecken. Denn Kommentare auch in den HTML, PHP und JSP, Java oder JavaScript Überhand nehmen, nimmt die Dokumentation eines Projektes zuviel KB und Arbeit in Anspruch. Denn dies setzt unter anderem auch voraus, dass diese Dokumentationen von allen Mitarbeitern mit gleicher Beachtung und Intensität über Jahre hinweg durchgeführt werden.

Permanenter Link

Dirk
am 03.12.2007 - 10:36

Und wie die iehacks.css (11KB) verdeutlicht ist sie ohne Kommentare mit 2KB wesentlich kleiner.

Natürlich wächst die Dateigröße. Ich empfehle daher bei größeren Projekten generell eine Unterscheidung zwischen einer Entwicklerfassung und optimierten Stylesheets für die Produktivumgebung. Mit Tools wie CSSTidy geht die Optimierung leicht von der Hand. Auf diese Weise lassen sich beide Wünsche - Kommentare und kleine Dateigröße im Live-Betrieb - bei geringfügigem Mehraufwand erreichen.

Denn dies setzt unter anderem auch voraus, dass diese Dokumentationen von allen Mitarbeitern mit gleicher Beachtung und Intensität über Jahre hinweg durchgeführt werden.

Da stimme ich Dir zu. Allerdings liegt die Entscheidung darüber, diese Arbeit permantent und gleichbleibender Qualität zu leisten, einzig und allein beim Entwickler selbst. Diese Entscheidung ist damit unabhängig davon, mit welcher Technik man letztlich arbeitet sondern letzten Endes nur dem eigenen Anspruch an den Code geschuldet.

Bei denjenigen die professionell diese Arbeiten machen, kann bzw. sollte man diese Kenntnisse darüber voraussetzen. Oder nicht?

Nein, ich denke nicht. Nicht jeder von uns ist automatisch Spezialist in Sachen Barrierefreiheit, Suchmaschinenoptimierung, CSS-Bugs ... nur weil man damit seine Brötchen verdient. Ich beschäftige mich nun schon eine Weile mit CSS-Bugs und muss trotzdem gelegentlich nachschlagen. Es gibt auch keinen Grund, alles im Kopf haben zu müssen. Bugs sind nicht das wichtigste im Webdesign sondern eher eine lästige Randerscheinung.

Permanenter Link

Matthias
am 03.12.2007 - 12:46

Das Beispiel
/**
* 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 }

erscheint mir sinnvoll für z. B. Netzgestalter, die sich mit CSS nicht auskennen, aber erkannt haben, dass man heute mit DTP (Desktop Publishing) keine Webseiten mehr zustande bringt, die möglichst universell funktionieren sollen.

Weil die Erkenntnis da ist, dass man mit Klick-Klick-Klick-und-Fertig-ist-die-Webseite nicht mehr wettbewerbsfähig ist, eröffnet die Möglichkeit der automatischen Erstellung von Modul-/Programmdokumentationen mittels CSSDOC sicher Hilfestellung im Umgang mit CSS und dem Lernprozess, der mit der Neuorientierung einhergeht.

Vielleicht wäre

/* Dbl. Float-Margin Bug, Fix IE5x+6 win */
.float_left { float:left; display:inline }

(oder so ähnlich) eine ebenso gangbare "Shorthand"-Alternative.
CSSDOC schafft da natürlich mehr Struktur durch Ordnungselemte wie
@valid yes.
Werden diese internen CSS-Metas wirklich immer benötigt?

Nicht nur DTP werden nützliche Hilfen, wie solche erläuternden Kommentare warscheinlich zu schätzen wissen.

Permanenter Link

Dorothea Schäfer
am 04.12.2007 - 00:42

Hallo,

eine gute Idee!

Gibt es denn analog zu javadoc auch schon ein Tool mit dem man automatisch eine Dokumentation erstellen kann? Idealerweise mit Einbindung der HTML, PHP etc Dateien und deren Hierarchie.

Ich freue mich schon auf die nächsten Türchen!

--- Vielen Dank! ---

Grüße Dorothea Schäfer

Permanenter Link

Daniel
am 04.12.2007 - 01:39

Ich hatte neulich schon im Technikwürze Podcast mal reingehört und werde das nun einfach mal im nächsten Projekt testen.

Permanenter Link

Frank
am 04.12.2007 - 12:23

Mir gefällt die Idee sehr gut! Schön wäre es, wenn CSSTidy die Kommentare parst.

Danke für den Beitrag!

Permanenter Link

David
am 05.12.2007 - 14:36

Ich verwende CSSDOC schon seit einiger Zeit. Man gewinnt deutlich mehr Überblick und die Motivation zum sinnvollen Kommentieren erscheint mir (auch bei den Kollegen) größer. Durch die Tags wird das Wichtige einfacher auf den Punkt gebracht.

Eigentlich erstaunlich, dass sich sowas erst jetzt durchzusetzen beginnt.

Danke für deinen Einsatz, Dirk!

Permanenter Link

Dirk
am 06.12.2007 - 15:14

@Matthias

Werden diese internen CSS-Metas wirklich immer benötigt?

Informationen darüber, ob ein Bugfix validen Code enthält oder nicht, sollen nicht den obligatorischen Durchlauf eines CSS-Validators ersetzen. Sie sind viel mehr als Achtungszeichen zu sehen, falls das CSS durch Tools wie CSSTidy optimiert werden soll. In diesem Fall sollte der Anwender darauf achten, dass das Optimierungstool den ggf. nicht-validen Hack nicht zerstört.

Frank Bültge hat in seinem heutigen Blogpost sogar bereits eine erste Einbindung von CSSDOC in UltraEdit vorgestellt, wechle die verschiedenen Tags einsatzbereit vorhält. Vielen Dank an Frank für das tolle Feedback auf den Advendskalender-Artikel.

@Dorothea

Gibt es denn analog zu javadoc auch schon ein Tool mit dem man automatisch eine Dokumentation erstellen kann?

Nein, noch gibt es solche Tools leider nicht. Tom Klingenberg steckt derzeit über beide Ohren in der Ersarbeitung einer ersten vollständigen Spezifikation aller Tags einschließlich deren Handhabung. Eine Vorabversion liegt bereits seit einigen Wochen im Netz und freut sich über jedes Nutzerfeedback.

Erst wenn diese "technischen Anwendungsregeln" vorliegen, können Programmierer sich daran machen, die Unterstützung für CSSDOC in ihre Software zu implementieren.

@David

Eigentlich erstaunlich, dass sich sowas erst jetzt durchzusetzen beginnt.

Stimmt. Auf der anderen Seite, schau Dir Javascript an. Das gibts schon ewig, hat aber erst durch die zahlreichen aktuellen Bibliotheken neuen Auftrieb gewonnen. Hoffen wir also auf ähnliche Effekte.

Beste Grüße
Dirk

Permanenter Link
Matthias Koch

Matthias Koch (Webkraut)
am 07.12.2007 - 03:59

@Dirk

Ohne Frage steckt da viel Arbeit drin und verdient Anerkennung.

Permanenter Link

Rob
am 16.12.2007 - 12:21

Interessanter Beitrag. Obwohl es ja noch ein sehr junges Projekt scheint, werde ich das in meinem nächsten Projekt verwenden.

Gruss
Rob

Permanenter Link

Ralph
am 14.04.2008 - 21:24

Ich habe zwar auch meine eigene Struktur für meine CSS - Dateien, aber ich werde mir dieses Projekt in Ruhe mal genauer anschauen. Danke für diesen Hinweis.

Ralph

Permanenter Link

Die Kommentare sind geschlossen.