Die Optionen für die programmatische Dokumentation von CSS

Ich bin fest davon überzeugt, dass die Dokumentation so nah wie möglich am Code aufbewahrt werden sollte. Meiner Erfahrung nach ist das die einzige Option, die langfristig gut funktioniert. Externe Dokumente, Notizen und Wikis veralten, werden vergessen und gehen verloren.

Dokumentation ist ein Thema, das mich immer beschäftigt. Die Arbeit an einer schlecht dokumentierten Codebasis ist eine tickende Zeitbombe. Sie macht den Onboarding-Prozess zu einer mühsamen Erfahrung. Eine andere Sichtweise auf schlechte Dokumentation ist, dass sie zu einem niedrigen Truck-Faktor beiträgt (d. h. „die Anzahl der Personen in Ihrem Team, die von einem LKW überfahren werden müssen, bevor das Projekt in ernsthafte Schwierigkeiten gerät“).

Vor kurzem wurde ich in ein Projekt eingearbeitet, das mehr als 1.500 Seiten Dokumentation in… Microsoft Word enthielt. Es war veraltet und unorganisiert. Eine echte Katastrophe. Es muss einen besseren Weg geben!

Ich habe bereits früher über dieses Dokumentationsproblem gesprochen. Ich habe vor kurzem hier auf CSS-Tricks in meinem Artikel Wie sieht eine gut dokumentierte CSS-Codebasis aus? darüber gesprochen. Lassen Sie uns nun die Optionen für die *programmatische* Dokumentation von Code untersuchen. Insbesondere CSS.

Ähnlich wie bei JSDoc gibt es auch in der CSS-Welt einige Möglichkeiten, Ihre Komponenten direkt im Quellcode als /* Kommentare */ zu beschreiben. Sobald Code auf diese Weise durch Kommentare beschrieben wird, kann ein lebendiger Styleguide für das Projekt generiert werden. Ich hoffe, ich habe das Wort lebendig ausreichend betont, da ich glaube, dass dies der Schlüssel für eine erfolgreiche Wartung ist. Basierend auf meinen Erfahrungen gibt es eine Reihe von Vorteilen, Code auf diese Weise zu dokumentieren, die Sie sofort erleben.

• Das Team beginnt, eine gemeinsame Terminologie zu verwenden, wodurch Kommunikationsprobleme und Missverständnisse erheblich reduziert werden.
• Der aktuelle Zustand der visuellen Benutzeroberfläche Ihrer Komponenten ist immer präsent.
• Hilft dabei, Front-End-Codebasen mit minimalem Aufwand in gut beschriebene Pattern Libraries zu verwandeln.
• Nützlich als Entwicklungs-Spielwiese.

Es wird manchmal argumentiert, dass ein entwicklungszentrierter Ansatz für die Dokumentation recht zeitaufwendig ist. Dem werde ich nicht widersprechen. Man sollte immer versuchen, ein Gleichgewicht zwischen der Erstellung von Funktionalität und dem Schreiben von Dokumentation zu finden. Zum Beispiel verwenden wir in dem Team, in dem ich gerade arbeite, einen agilen Ansatz zur Erstellung von Dingen, und es gibt Zeitblöcke in jedem Sprint, die der Vervollständigung fehlender Dokumentationen gewidmet sind.

Natürlich gibt es Zeiten, in denen funktionierende Software eine umfassende Dokumentation übertrifft. Das ist völlig in Ordnung, solange die Verantwortlichen sich dessen bewusst sind und einen Plan haben, wie das Projekt langfristig gewartet wird.

Schauen wir uns nun die beliebtesten Dokumentationsoptionen in CSS an.

Knyle Style Sheets (KSS)

KSS ist eine Spezifikation für Dokumentation und ein Format für Styleguides. Es versucht, eine Methodik für das Schreiben von wartbarem, dokumentiertem CSS innerhalb eines Teams bereitzustellen. Die meisten Entwickler in meinem Netzwerk verwenden es aufgrund seiner Popularität, Ausdrucksstärke und Einfachheit.

Das KSS-Format ist menschlich lesbar und maschinell parsinbar. Daher soll es die Automatisierung der Erstellung eines lebendigen Styleguides unterstützen.

Ähnlich wie bei JSDoc werden in KSS CSS-Komponenten direkt im Quellcode als Kommentare beschrieben. Jeder KSS-Dokumentationsblock besteht aus drei Teilen: einer Beschreibung, was das Element tut oder wie es aussieht, einer Liste von Modifikatorklassen oder Pseudoklassen und wie sie das Element modifizieren, und einem Verweis auf die Position des Elements im Styleguide. Hier ist, wie es aussieht.

// Primary Button
//
// Use this class for the primary call to action button.
// Typically you'll want to use either a `<button>` or an `<a>` element.
//
// Markup:
// <button class="btn btn--primary">Click Me</button>
// <a href="#" class="btn btn--primary">Click Me</a>
//
// Styleguide Components.Buttons.Primary
.btn--primary {
    padding: 10px 20px;
    text-transform: uppercase;
    font-weight: bold;
    bacgkround-color: yellow;
}

Benjamin Robertson beschreibt detailliert seine Erfahrungen mit kss-node, einer Node.js-Implementierung von KSS. Darüber hinaus gibt es eine Reihe von Generatoren, die die KSS-Notation verwenden, um Styleguides aus Stylesheets zu generieren. Eine beliebte Option, die erwähnenswert ist, ist der SC5 Style Generator. Darüber hinaus wird ihre Dokumentationssyntax mit Optionen erweitert, um Wrapper-Markup einzuführen, Teile des Stylesheets von der Verarbeitung auszuschließen und andere wünschenswerte Verbesserungen.

Andere, manchmal nützliche (aber meiner Meinung nach meist nur schicke) Dinge sind

• Mit dem Designer-Tool können Sass-, Less- oder PostCSS-Variablen direkt über die Weboberfläche bearbeitet werden.
• Es gibt eine Live-Vorschau der Stile auf jedem Gerät.

Wer weiß, vielleicht sind sie für einige Anwendungsfälle vorteilhaft. Hier ist eine interaktive Demo von SC5.

Im Gegensatz zur JavaScript-Welt, in der JSDoc König ist, gibt es immer noch eine Reihe von Tools, die die KSS-Konventionen nicht verwenden. Lassen Sie uns daher zwei Alternativen untersuchen, die ich kenne, geordnet nach Popularität, aktuellen Updates und meiner subjektiven Meinung.

MDCSS

Wenn Sie nach einer einfachen, prägnanten Lösung suchen, könnte mdcss die Antwort sein. Hier ist eine interaktive Demo. Um einen Dokumentationsabschnitt hinzuzufügen, schreiben Sie einen CSS-Kommentar, der mit drei Bindestrichen --- beginnt, wie hier:

/*---
title:   Primary Button
section: Buttons
---

Use this class for the primary call to action button.
Typically you'll want to use either a `<button>` or an `<a>` element

```example:html
<button class="btn btn--primary">Click</button>
<a href="#" class="btn btn--primary">Click Me</a>
```
*/
.btn--primary {
    text-transform: uppercase;
    font-weight: bold;
    background-color: yellow;
}

Der Inhalt eines Dokumentationsabschnitts wird von Markdown analysiert und in HTML umgewandelt, was sehr gut ist! Darüber hinaus kann der Inhalt eines Abschnitts automatisch aus einer anderen Datei importiert werden, was für detailliertere Erklärungen sehr nützlich ist.

/*---
title:  Buttons
import: buttons.md
---*/

Jedes Dokumentationsobjekt kann eine Reihe von Eigenschaften wie Titel (des aktuellen Abschnitts), eindeutigen Namen, Kontext und einige andere enthalten.

Einige andere Tools, die mir aufgefallen sind und sehr ähnliche Funktionalitäten bieten, sind:

• Styledown | Interaktive Demo
• Aigis | Interaktive Demo

Nucleus

Nucleus ist ein Generator für lebendige Styleguides für Komponenten, die auf Atomic Design basieren. Nucleus liest die Informationen aus DocBlock-Annotationen.

Atomic Design ist eine Richtlinie für das Schreiben modularer Stile, die verschiedene Komplexitätsgrade auf einer (bio-)chemischen Skala projizieren. Dies führt zu einer geringen Selektorspezifität und ermöglicht es Ihnen, komplexe Entitäten aus einfachen Elementen zu komponieren. Wenn Sie mit Atomic Design nicht sehr vertraut sind, kann die Lernkurve anfangs etwas überwältigend erscheinen. Die Entitäten für Nucleus umfassen:

• Nuklide: Nicht direkt verwendbar, nur Stile (Mixins, Einstellungen, Variablen).
• Atome: Einzelklasse-Elemente oder Selektorregeln (Buttons, Links, Überschriften, Eingabefelder usw.).
• Moleküle: Eine oder mehrere verschachtelte Regeln, aber jede von ihnen ist nicht mehr als ein Atom.
• Strukturen: Die komplexesten Typen, können aus mehreren Molekülen oder anderen Strukturen bestehen.
• … und einige mehr.

Das Button-Beispiel, das wir hier in diesem Artikel verwenden, steht für ein Atom – ein sehr grundlegendes Element der Stylesheet (Einzelklasse-Element oder Selektor). Um es als Atom zu kennzeichnen, müssen wir es mit dem Tag @atom annotieren, gefolgt vom Namen der Komponente.

/**
 * @atom Button
 * @section Navigation > Buttons
 * @modifiers
 *  .btn--primary - Use this class for the primary call to action button.
 * @markup
 *  <button class="btn">Click me</button>
 *  <button class="btn btn--primary">Click me</button>
 *  <a href="#" class="btn btn--primary">Click Me</a>
 */
.btn--primary {
    text-transform: uppercase;
    font-weight: bold;
    bacgkround-color: yellow;
}

Hier ist eine interaktive Demo.

Fazit

Es gibt noch keinen eindeutigen Gewinner in Bezug auf ein Tool oder eine gemeinsame Syntaxdefinition für die programmatische Dokumentation von CSS.

Einerseits scheint KSS die Gruppe anzuführen, daher würde ich sagen, es lohnt sich, es für ein Langzeitprojekt in Betracht zu ziehen. Mein Bauchgefühl ist, dass es lange Bestand haben wird. Andererseits sehen verschiedene Syntaxoptionen und Tools wie Nucleus und MDCSS ebenfalls vielversprechend aus. Ich würde Sie ermutigen, sie bei Kurzzeitprojekten auszuprobieren.

Es ist wichtig zu beachten, dass alle in diesem Artikel vorgestellten Tools ihre Arbeit gut erledigen und skalierbar genug erscheinen. Probieren Sie sie also aus und wählen Sie, was für Ihr Team am sinnvollsten ist.

Ich würde mich freuen, wenn Sie in den Kommentaren unten mitteilen, ob Sie eines dieser oder andere bemerkenswerte Tools kennen oder damit Erfahrung haben!