Dokumentation der CSS-Codebase

Warum CSS nicht einfach nur programmiert, sondern auch kommentiert werden sollte

Unter Web-Entwicklern herrscht größtenteils Einigkeit über die Bedeutung der Dokumentation in z.B. PHP oder JavaScript. Unglücklicherweise ist dies für CSS nur selten der Fall. So kann es vorkommen, dass Sie vor einem CSS-Projekt stehen und sich nur geringer oder überhaupt keiner Dokumentation gegenüber sehen.

Obwohl CSS vergleichsweise einfach zu schreiben ist, ist es durch seine Exaktheit, seinen globalen Geltungsbereich und den Mangel an Orientierung aufwendig in der Wartung. Das kann schnell zu Codeduplizierung, Unregelmäßigkeiten und einer zu komplexen Programmierung führen.

Es ist häufig überraschend, wenn Entwickler behaupten, dass es unnötig wäre CSS zu kommentieren. Offenbar hatten diese Entwickler noch nie mit riesigen Layouts zu tun. Wenn Sie sich einmal in das Layout eingearbeitet haben, mögen viele der Entscheidungen nachvollziehbar sein, aber wenn Sie einmal mit einer gut dokumentierten CSS-Entwicklung gearbeitet haben, dann wissen Sie sicher wie angenehm das sein kann.

Häufig müssen Sie nämlich Stunden damit verbringen, herauszufinden was der Entwickler beabsichtigte als er den spezifischen Code implementierte und sich nicht für eine Alternative entschieden hat. Das ist nicht nur zeit-, sondern auch Nerven raubend.

Deshalb lassen Sie uns doch einen Blick auf die Merkmale einer gut dokumentierten CSS-Basis werfen.

1) CSS-Tools - Mehr als ein Werkzeug für den Job

Oft finden sich im Code-Bibliotheken von Drittanbietern, Mixins und weitere Werkzeuge, die die CSS-Basis ergänzen. Der Paketmanager führt zwar die eingefügten Addons auf, gibt allerdings keinerlei Auskunft darüber, warum die Entscheidung getroffen wurde, diese Addons zu benutzen oder was ihre genaue Funktion beinhaltet.

Nützlich wäre hier eine Beschreibung der Gründe für die Implementierung der jeweiligen Addons. So ist es zum Beispiel möglich, dass ein Tool eingeführt wurde, um ein Problem mit CSS zu lösen, welches inzwischen gelöst wurde. Mit ausreichend Kontext, sprich Kommentierung, können Sie die Gründe dafür nachvollziehen und entsprechende Entscheidungen treffen.

Manchmal finden sich unzählige dieser Drittanbieter-Tools in einem Projekt und Sie müssen jedes einzeln im Internet nachschlagen und selbst herausfinden, wozu es implementiert wurde. Das ist nicht nur mühsam, sondern auch zeitraubend.

In einem gut dokumentierten Code ist jedes implementierte Tool entsprechend kommentiert. Oft genügt ein Kommentar von der Länge eines Tweets (140 Zeichen), in dem Sie die Gründe für die Implementierung knapp darlegen. Damit helfen Sie jedem, der sich neu in den Code einarbeiten muss, sowie auch sich selbst, wenn Sie später einzelne Codesegmente überprüfen. Idealerweise fügen Sie den Kommentar genau da ein, wo Sie auch das Tool implementiert haben.

2) CSS-Konventionen - Eine Sprache, viele Dialekte

Gutes Coding beinhaltet einen konsistenten, lesbaren und eindeutigen Quellcode. Struktur und Stil einer Anwendung sind standardisiert, sodass auch andere den Code leicht lesen und verstehen können.

Ebenso wichtig sind die projektspezifischen Namensgebungskonventionen oder -methoden. Beispiele dafür sind BEM, OOCSS, SMACSS oder ACSS. Es gibt Fälle, in denen bestimmte Prinzipien zwar theoretisch angewandt wurden, in der Praxis dann allerdings durch die Vorlieben der Entwickler individuell modifiziert wurden. Eine Richtlinie wie strikt diesen Prinzipien zu folgen ist, ist folglich ein weiteres Merkmal eines gut dokumentierten Quellcode.

Das ist allerdings nur ein Teil der Konventionen, die Sie beachten müssen. Andere Informationen, die in dem CSS Style Guide stehen sollen, betreffen die Sektionierung, Strukturierung, Kommentierung, Formatierung, die Ordnung von Attributen, etc. All diese Informationen in einem CSS Style Guide zu dokumentieren, hilft Ihnen einen konsistenten und verständlichen Quellcode zu generieren.

3) CSS Architektur - Jeder baut anders

Die meisten skalierbaren Projekte folgen einer bestimmten Art von Architektur, das heißt, dass einzelne Elemente in einer bestimmten Ordnung im Quelltext auftauchen sollten. Die Grundlagen dieser Ordnung sollten in einem gut dokumentierten Quelltext dargelegt werden um Strukturierung und Sektionierung zu verdeutlichen.

Die Bedeutung der Dokumentation der Architektur eines CSS-Textes liegt in CSS selbst. CSS ist deklarativ, wodurch es keiner eigenen Logik folgt, welcher den Entwicklern vorgibt, in welcher Art das Projekt aufgebaut wird. Es operiert auf globaler Ebene, wodurch es zu Kollisionen, Lecks und Regressionen kommt. Weiterhin nutzt es ein Vererbungsprinzip, wodurch alle Elemente auf eine Art ineinander übergreifen, was den Text wiederum auf eine Art zerbrechlich macht. Schließlich kann auch das Spezifikation-Modell zu Problemen führen, wenn verschiedene Selektoren miteinander um Vorrang ringen.

Deshalb ist es von Vorteil in einem CSS Projekt einem Prinzip wie zum Beispiel ITCSS zu folgen, wenn Sie an einem Projekt arbeiten. Oft finden sich ähnliche Prinzipien, die versuchen diese Probleme zu beseitigen, bereits in größeren Projekten. In einem gut dokumentierten Quelltext, sollten Sie also erwarten diese Prinzipien vorzufinden.

Wenn Sie sich unsicher sind, ob Ihre eigene Dokumentation hinreichend genau ist, fragen Sie sich, wo neue Styles oder Stylesheets hinzugefügt werden sollen. Können Sie diese Frage beantworten, ist Ihre Architektur ausreichend dokumentiert.

4) CSS-Patterns und was Bibliotheken damit zu tun haben

Für gewöhnlich werden Logikmodule in CSS-Komponenten oder Blöcke eingeteilt. Auch wenn Sie einige davon nicht wiederverwenden können, so bilden diese doch die einzelnen Bausteine für Ihr Projekt. Deshalb sollte der Beschreibung dieser Bausteine eine hohe Priorität in einem gut dokumentierten Quelltext zukommen.

Ideal ist es, wenn Sie die Container sortieren und in Gruppen einordnen, benennen und Regeln für diese einführen, um einen Überblick über alle Komponenten zu gewähren. Eine gut beschriebene CSS-Komponente beinhaltet nicht nur die Funktionsweise, sondern auch den HTML-Markup sowie den Kontext in welchem Sie die Komponente verwenden sollen. Darauf aufbauend entsteht eine sogenannte Pattern Library. Diese beinhaltet eine Sammlung der Komponenten, die Sie wiederverwenden können, um eine Website zu erstellen. Da modulare, Komponenten-basierte Architektur gerade im Trend liegt, sind diese sehr wertvoll.

Eine Pattern Library dient der Verdeutlichung was mit existierenden Komponenten (patterns) erstellt werden kann. Komponenten sollten prinzipiell im Hinblick auf Ihre Tags, ein Beispiel und die Version inklusive älterer Versionen beschrieben werden. Zusätzliche Informationen beinhalten die Performance, die Zugänglichkeit, sowie verwandte Patterns. Diese Liste ist nicht vollständig und soll nur einige Ideen geben. Im Endeffekt richtet Sie sich nach den Bedürfnissen Ihres eigenen Projektes.