Wie sieht eine gut dokumentierte CSS-Codebasis aus?

In der Frontend-Community gibt es viel Aufmerksamkeit für die Dokumentation von JavaScript. Das ist bei CSS nicht so sehr der Fall. Oft fühle ich mich verloren, wenn ich einem Projekt mit minimaler oder keiner CSS-Dokumentation beitrete.

Auch wenn CSS relativ einfach zu schreiben ist, kann es recht schwer zu pflegen sein. Die Spezifität, der globale Geltungsbereich von allem und der Mangel an Führung können leicht zu Inkonsistenz, Code-Duplizierung und Überkomplizierung führen.

Ich war schon lange neugierig, wie eine wirklich gut dokumentierte CSS-Codebasis aussieht. Hier teile ich meine Erfahrungen und die Erwartungen, die ich an meine Vision gut dokumentierter Stylesheets habe.

Es überrascht mich, wenn Leute sagen, dass das Kommentieren von CSS nicht so wichtig sei. Ich stelle mir vor, dass keiner von ihnen sich mit mehr als 10.000 Zeilen Stylesheets auseinandersetzen musste! Oft habe ich damit gekämpft, welches HTML zu welchem spezifischen Stil führt. Ohne soliden Kontext zu den getroffenen Entwicklungsentscheidungen erhöhen sich die Debugging-Aufwände. Auch die WTFs pro Minute steigen exponentiell an.

Viele Male habe ich Stunden damit verbracht, herauszufinden, was der Entwickler beabsichtigt hat, warum er es nicht anders gemacht hat, warum dieses Layout scheinbar so komplex ist. In diesen "Warum"-Fragen steckt viel Schmerz.

Also, los geht's! Untersuchen wir die 4 großen Anzeichen einer gut dokumentierten CSS-Codebasis.

1) CSS-Technologie-Stack & Toolchain

Es gibt wahrscheinlich Dinge in unserer CSS-Codebasis wie Drittanbieter-Bibliotheken, Mixins oder andere Tools. Ein Blick in die Abhängigkeitsliste des Paketmanagers gibt wenig Kontext darüber, *warum* die Entscheidung getroffen wurde, diese Dinge hinzuzufügen, was sie genau tun und wie wir sie verwenden.

Es wäre gut für alle, zu wissen, warum eine bestimmte Bibliothek oder ein bestimmtes Tool eingeführt wurde. Stellen Sie sich zum Beispiel vor, dass eine Drittanbieter-Bibliothek nur eingeführt wurde, um ein mittlerweile veraltetes CSS-Problem zu lösen. Wenn wir solche Kontexte hätten, könnten wir fundiertere Entscheidungen treffen.

Es kann manchmal recht viele Drittanbieter-Bibliotheken in einem Projekt geben. Haben Sie sich schon einmal stundenlang durchs Web gesucht, um jede einzelne herauszufinden, was sie überhaupt ist? Es kann eine ziemliche Herausforderung sein, zu wissen oder den Überblick zu behalten, was jede einzelne genau tut.

Eine gut dokumentierte Codebasis würde eine Beschreibung für jede Abhängigkeit enthalten. Vielleicht könnten Sie einen Code-Kommentar in Tweet-Länge (140 Zeichen) einfügen, der erklärt, warum sie vorhanden ist. Das würde jedem anderen in der Codebasis einen Vorsprung verschaffen, warum etwas da ist.

Ich füge diese Beschreibungen gerne dort ein, wo ich sie mit @import importiere.

2) CSS-Konventionen

Gute Coding-Konventionen führen zu konsistentem, lesbarem und eindeutigem Quellcode. Sie standardisieren die Struktur und den Codierungsstil einer Anwendung, sodass Sie und andere den Code leicht lesen und verstehen können.

Es ist wichtig zu wissen, ob es projektspezifische Namenskonventionen oder Methodologien gibt (wie BEM, OOCSS, SMACSS oder ACSS). Ich habe Fälle gesehen, in denen Prinzipien einer bestimmten Methodologie angewendet wurden, aber die tatsächlich befolgten Regeln basierend auf den Vorlieben der beteiligten Entwickler modifiziert wurden. Eine Angabe, wie streng wir die Prinzipien der Methodologie befolgen müssen, wäre also gut in einer gut dokumentierten Codebasis zu hinterlassen.

Dies wirft die größere Frage nach CSS-Styleguides auf. Eine Namenskonvention ist nur eine Wahl als Teil einer vollständigen Styling-Strategie. Andere Teile könnten sein

• Wie ist der Code unterteilt?
• Wie sind die Dateien strukturiert?
• Wie sind die Eigenschaften angeordnet?
• Wie erfolgt die Kommentierung?
• Wie erfolgt die Formatierung (Einrückung, Regeldeklarationen)?
• Wie werden JavaScript-Hooks an Klassen gebunden?
• … und viele weitere Regeln oder Anti-Patterns wie Verschachtelung mehr als 3 Ebenen tief, Vermeidung von ID-Selektoren, Verwendung von !important nur für Utility-Klassen und so weiter.

All dies macht einen vollständigen CSS-Styleguide aus. Ein gemeinsames Vokabular wie dieses würde ich als starken Pluspunkt für Konsistenz betrachten.

3) CSS-Architektur

Die meisten skalierbaren Projekte folgen einer Art von Architektur in Bezug auf die Anordnung von Styles. In einer gut dokumentierten Codebasis sollten die grundlegenden Prinzipien erwähnt werden, denen das Projekt beim Strukturieren und Unterteilen von Styles folgt.

Ich wurde zuerst dazu inspiriert, CSS-Architektur zu erforschen, indem ich Harry Roberts' Vortrag über die Verwaltung von CSS-Projekten ansah. Hier ist Harry:

CSS-Architektur scheint derzeit sehr angesagt zu sein. Sie haben dies zweifellos in den letzten ein oder zwei Jahren schon oft gehört, und das aus gutem Grund: UIs (und die Teams, die sie erstellen) werden immer größer und komplexer als je zuvor.

Es gibt eine Reihe von Aspekten von CSS, die es problematisch machen. Es ist deklarativ, das heißt, es gibt keine Logik oder keinen Kontrollfluss, der anderen Entwicklern viel über den Zustand oder die Konstruktion des Projekts erzählen würde. Es arbeitet in einem globalen Namensraum, was Kollisionen, leckende Styles und unbeabsichtigte Regressionen bedeutet. Es nutzt Vererbung, was alles etwas voneinander abhängig und fragil macht. Schließlich kann das unvermeidliche Spezifitätsmodell Probleme verursachen, wenn sich Selektoren um Vorrang streiten.

Daher stellt er ein Konzept für die Architektur von CSS namens ITCSS vor. Wenn Sie an einem Projekt von angemessener Größe arbeiten, gibt es wahrscheinlich bereits ähnliche Prinzipien oder Ideen, die darauf abzielen, diese Probleme zu lösen. In einer gut dokumentierten Codebasis würde ich daher erwarten, sie irgendwo niedergeschrieben zu sehen.

Man könnte erkennen, ob die Architektur gut genug erklärt ist, wenn man folgende Frage beantworten kann: Wo sollen neue Styles oder Stylesheets hinzugefügt werden?

4) CSS-Komponentenbeschreibungen und Beispiele

Ein gängiges Muster ist, die logischen Module in CSS-Komponenten (oder "Blöcke" nach BEM) zu trennen. Einige davon sind vielleicht wiederverwendbar, andere nicht, aber wichtig ist, dass sie die Bausteine unseres Projekts sind. Daher sollte die Beschreibung, was sie sind, in einer gut dokumentierten Codebasis oberste Priorität haben.

Idealerweise sollten Sie sie anordnen und gruppieren, benennen und Regeln zwischen ihnen aufstellen, um einen Überblick über alle Komponenten zu erhalten. Eine gut beschriebene CSS-Komponente enthält nicht nur Informationen darüber, was die Komponente tut, sondern auch andere wertvolle Informationen wie beispielhafte HTML-Markup und den Kontext, in dem sie verwendet werden soll. Ein Schritt weiter führt zu Pattern Libraries. Eine Pattern Library ist eine Sammlung wiederverwendbarer Komponenten, die gemeinsam zur Erstellung einer Website verwendet werden können. Mit dem Trend zu modularen, komponentenbasierte Architekturen können sie einen enormen Wert bringen.

Das Ziel einer Pattern Library ist es, zu zeigen, was mit vorhandenen Mustern (Komponenten) gebaut werden kann. Aber schauen wir uns an, welche zusätzlichen Informationen neben jedem Muster angezeigt werden können. Vitaly Friedman gab eine gute Zusammenfassung darüber, wie die Pattern Library auf die nächste Stufe gehoben wird. Er stellt fest, dass es nicht ausreicht, sich auf Komponenten zu konzentrieren.

Eines der Hauptprobleme bei Pattern Libraries ist, dass sie zwar einen Überblick über Komponenten geben, aber oft viel Interpretationsspielraum lassen. Komponenten können auf vielfältige Weise, konsistent und inkonsistent, kombiniert werden. Es ist großartig, zu sehen, welche Schaltflächenvarianten und Ikonografien verfügbar sind und welche Arten von Tabellen und Preistags man verwenden kann, aber was ist, wenn Sie eine Benutzeroberfläche entwerfen oder erstellen müssen, die all diese Komponenten gleichzeitig enthält – und vielleicht eine, die in der Bibliothek noch nicht existiert?

Eine Liste von Modulen allein würde keinen Kontext oder keine spezifischen Informationen darüber vermitteln, wie die Module verwendet werden (sollten und nicht sollten).

Basierend auf Vitalys Beitrag und Brad Frosts Anatomie eines Musters in einer Pattern Library, hier sind einige Ideen, die jede unserer Muster (Komponenten) haben könnte, abgesehen vom üblichen eindeutigen Namen, Code-Beispiel und einer Beschreibung des Zwecks der Komponente. Grundlegend (fundamental)

• Tags oder Kategorien: Die zugewiesenen Tags oder Kategorien für die Komponente. Entwickler könnten ihre Komponenten mit Tags wie "in Gebrauch", "muss refaktoriert werden" usw. versehen.
• Responsive Vorschau: Eine reale, größenveränderbare Vorschau der Komponente, die den tatsächlichen Code-Snippet verwendet, der in der Produktion verwendet wird. Alternativ nur ein Screenshot.
• Versioning und Legacy, beteiligte oder verantwortliche Teammitglieder: In einem größeren Team kann die Zuständigkeit für die (Familie der) Komponenten und welche Teammitglieder sie aktiv entwickelt haben, für die Wartung und Weiterentwicklung sehr hilfreich sein.

… und hier sind einige fortgeschrittenere

• Performance-Auswirkungen: Manchmal kann CSS auch schwer sein. Ein Hinweis auf die Performance oder ein Abschnitt mit "Warnhinweisen", der nicht nur die Performance-Auswirkungen, sondern auch häufige Pannen bei falscher Verwendung des Musters darlegt.
• Zugänglichkeitsimplikationen: Hinweis auf Zugänglichkeitsanforderungen. Einige Komponenten erfordern möglicherweise mehr Aufwand, um die Zugänglichkeit aufrechtzuerhalten, insbesondere wenn sie mit anderen Komponenten interagieren.
• Verwandte Muster: Ein schneller Überblick über verwandte Komponenten oder die Familie von Komponenten, zu denen eine bestimmte Komponente gehört. Könnte eine Erklärung enthalten, wann eine Komponente verwendet werden sollte, wann nicht und warum.
• Fallback- und Druckvorschauen.

… die Liste geht endlos weiter, je nachdem, was für Ihren spezifischen Anwendungsfall sinnvoll ist.

Fazit

Eine gut dokumentierte CSS-Codebasis erzwingt Konsistenz, steigert die Wartbarkeit und hilft dem Team, ein gemeinsames Vokabular aufzubauen. Sie ist eine Voraussetzung für effizientes CSS-Design und -Entwicklung. Darüber hinaus führt sie meiner Erfahrung nach zwangsläufig zu besserer Performance. Ich bin fest davon überzeugt, dass dies die Anzeichen für eine professionelle Projektausführung sind.

Wenn Sie Gedanken dazu haben, können Sie diese gerne in den Kommentaren unten hinzufügen, damit wir gemeinsam besseren Dokumentationspraktiken näherkommen.