CSS-Richtlinien, Teil 2. Kommentieren des Codes

Ursprünglicher Autor: Harry Roberts
  • Übersetzung
  • Tutorial


Jedes Projekt hat bestimmte Nuancen und Feinheiten, an die sich nicht jeder erinnert, und das Schlimmste, das einem Entwickler passieren kann, ist die Arbeit mit Code, den er nicht geschrieben hat. Selbst das Erinnern an die Feinheiten Ihres eigenen Codes ist nur bis zu einem gewissen Grad möglich, ganz zu schweigen von dem Code eines anderen. Deshalb muss CSS kommentiert werden .

CSS ist eine deklarative Sprache und oft schwer zu verstehen:
  • Dass ein Teil des Codes von einem anderen Teil abhängt;
  • Welche Auswirkung hat eine Änderung in einem bestimmten Teil des Codes zur Folge?
  • Wo sonst kann ich einen Code ohne neue Probleme verwenden;
  • Welche Stile ein bestimmtes Element erbt;
  • Welche Stile können ignoriert werden?
  • Wo der Entwickler den Code verwenden wollte.

Diese Liste berührt nicht einmal viele CSS-Macken, wie das Aktivieren der Hardwarebeschleunigung mithilfe von Eigenschaften transform, aber solche Dinge erschweren auch das Verständnis der Funktionsweise des Codes.

Da CSS allein möglicherweise nicht klar genug ist, profitieren Entwickler von Kommentaren zum Code.

In der Regel sollten Sie die Teile des Codes kommentieren, die der Entwickler nicht versteht, wenn Sie sie aus dem Kontext nehmen. Sie müssen nicht notieren color: red;, wodurch der Text rot wird. Wenn Sie jedoch beispielsweise eine Eigenschaft verwenden overflow: hidden;, um Floats zu löschen und Inhalte außerhalb des Blocks nicht auszublenden, sollten Sie einen erläuternden Kommentar hinzufügen.

Hochrangige Kommentare


Für umfangreiche Kommentare, die einen gesamten Abschnitt oder eine gesamte Komponente beschreiben, verwenden wir DocBlock-ähnliche mehrzeilige Kommentare, die unserer 80-Zeichen-Zeilenregel entsprechen.

Unten sehen Sie ein reales Beispiel für das Kommentieren des CSSWizardy-Website-Header-Codes.

/**
 * The site’s main page-head can have two different states:
 *
 * 1) Regular page-head with no backgrounds or extra treatments; it just
 *    contains the logo and nav.
 * 2) A masthead that has a fluid-height (becoming fixed after a certain point)
 *    which has a large background image, and some supporting text.
 *
 * The regular page-head is incredibly simple, but the masthead version has some
 * slightly intermingled dependency with the wrapper that lives inside it.
 */

Diese Kommentierungsebene sollte verwendet werden, um das Element im Allgemeinen zu beschreiben: seinen Zustand, wovon dieser Zustand abhängt und dergleichen.

Angabe der Stilvererbung

Wenn Sie mit einer großen Anzahl von Dateien arbeiten, befinden sich die miteinander verknüpften Regelsätze nicht immer in derselben Datei. Möglicherweise verfügen Sie über eine Hauptklasse .btn, die nur die Hauptstile der Schaltfläche enthält (z. B. Größen und Einzüge). Diese Klasse wird in der Komponentendatei erweitert, und ihr werden Stile hinzugefügt, um das gewünschte Erscheinungsbild zu erzielen. Wir müssen diese Beziehungen zwischen Objekten identifizieren, indem wir die Vererbung von Stilen angeben.

Zum Beispiel in einer Datei mit Hauptklassen (Objekten):

/**
 * Extend `.btn {}` in _components.buttons.scss.
 */
.btn {}

In der Datei mit untergeordneten Klassen:

/**
 * These rules extend `.btn {}` in _objects.buttons.scss.
 */
.btn--positive {}
.btn--negative {}

Das Kommentieren des Codes erfordert vom Entwickler keine großen Anstrengungen, und dank dieser Kommentare können diejenigen, die mit Ihrem Code arbeiten müssen, die Beziehungen zwischen den Klassen leicht herausfinden.

Low-Level-Kommentare


Oft müssen wir eine bestimmte Codezeile mit der Deklaration einer Eigenschaft kommentieren. Hierfür verwenden wir Fußnoten. Über den Link können Sie ein Beispiel für eine komplexere Kommentierung des oben erwähnten Header-Codes der Site sehen. Durch diese Art der Kommentierung können wir die gesamte Dokumentation an einem Ort aufbewahren und dann nur auf die richtige Stelle in der Dokumentation verweisen, anstatt einen langen Kommentar direkt in den Code zu schreiben.

Präprozessoren und Kommentierung


In vielen, wenn nicht allen Präprozessoren, können Kommentare hinzugefügt werden, die beim Kompilieren nicht in das endgültige Stylesheet ausgegeben werden. Machen Sie es sich zur Regel, solche Kommentare für Code zu verwenden, der auch nicht kompiliert wird. Verwenden Sie für den Code, der in die endgültige Datei ausgegeben wird, regelmäßige Kommentare.

So ist es richtig:

// Dimensions of the @2x image sprite:
$sprite-width:  920px;
$sprite-height: 212px;
/**
 * 1. Default icon size is 16px.
 * 2. Squash down the retina sprite to display at the correct size.
 */
.sprite {
    width:  16px; /* [1] */
    height: 16px; /* [1] */
    background-image: url(/img/sprites/main.png);
    background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */
}

In diesem Beispiel haben wir Variablen (die nicht kompiliert werden) mithilfe von Präprozessor-Kommentaren dokumentiert und für regulären Code die Standard-Kommentarmethode verwendet. Diese Methode stellt sicher, dass die kompilierten CSS-Dateien nur relevante und relevante Informationen für uns enthalten.

Kommentare entfernen


Es sollte beachtet werden, dass bei Verwendung des Codes in der Produktion alle Kommentare gelöscht und CSS selbst vor der Bereitstellung minimiert werden sollte.

Vorheriger Teil: CSS-Richtlinien, Teil 1. Syntax und Formatierung
Nächster Teil: CSS-Richtlinien, Teil 3. Klassennamen

Jetzt auch beliebt: