Codeguide von @mdo

Richtlinien zur Entwicklung von flexiblem, wartbarem und beständigem HTML und CSS.

Inhaltsverzeichnis

HTML

CSS

Goldene Regel

Halte dich immer an definierte Regeln - seien es diese, oder eigene. Große oder kleine Fehler - melde dich, wenn du Unstimmigkeiten gefunden hast. Um Beiträge zu diesem Styleguide zu liefern, öffne bitte ein Issue auf GitHub.

Jede Zeile Code sollte so aussehen, als wenn sie von einer Person geschrieben wurde, egal, wieviele wirklich daran gearbeitet haben.

HTML

Syntax

<!DOCTYPE html>
<html>
  <head>
    <title>Seitentitel</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 Doctype

Aktiviere den Standardmodus und konsistenteres Rendering in allen Browsern, indem der Doctype am Beginn jeder HTML Seite angegeben wird.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Sprachattribut

Aus der HTML5 Spezifikation:

Autoren wird empfohlen, ein Sprachattribut im Root-HTML Tag anzugeben, um die Sprache des Dokuments bekanntzumachen. Es hilft Sprachausgabetools die richtige Aussprache zu wählen, Übersetzungstools die richtigen Regeln zu verwenden, usw.

Weitere Informationen über das lang Attribut finden sich in den Spezifikationen.

Auf Sitepoint findet sich eine Liste der Sprachcodes.

<html lang="de-de">
  <!-- ... -->
</html>

IE Kompatibilitätsmodus

Der Internet Explorer unterstützt einen Kompatibilitätsmodus durch den <meta> Tag, um anzugeben, unter welcher IE Version die Seite gerendert werden soll. Sofern es andere Umstände nicht verlangen, sollte immer die modernste Version gewählt werden, indem der Edge Modus verwendet wird.

Weitere Informationen hält dieser hervorragende Stack Overflow Artikel bereit.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Zeichenkodierung

Das richtige Rendering des Inhalts kann schnell und einfach mit einer expliziten Zeichenkodierung festgelegt werden. Wenn die Zeichenkoderung auf diese Art gesetzt wurde, kann auf die einzelne Deklaration in HTML Elementen verzeichtet werden, sofern sie mit der des Dokumentes übereinstimmen (normalerweise UTF-8).

<head>
  <meta charset="UTF-8">
</head>

CSS und JavaScript includes

Nach den HTML5 Spezifikationen ist es nicht notwendig, einen type anzugeben, da CSS und JavaScript Dateien per Voreinstellung als text/css und text/javascript erwartet werden.

HTML5 Spezifikation links

<!-- Externes CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-Dokument CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Praktisch vor Rein

Bemühe dich, die HTML Standards und Semantik beizubehalten, aber nicht zum Preis von Praktikabilität. Benutze so wenig Markup mit den wenigsten Komplexitäten, wie möglich.

Attributreihenfolge

HTML Attribute sollten in der folgenden Ordnung erscheinen, um die Leserlichkeit zu erleichtern.

Klassen beinhalten wiederverwendbare Komponenten, also kommen sie zuerst. IDs sind eher spezifisch und sollten seltener verwendet werden (z.B. für seiteninterne Lesezeichen), also kommen sie als zweites.

<a class="..." id="..." data-modal="toggle" href="#">
  Beispiel link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Boolesche Attribute

Ein boolesches Attribute braucht keinen Wert. XHTML verlangt einen gegebenen Wert, aber HTML5 benötigt es nicht.

Weitere Informationen finden sich im WhatWG Abschnitt für boolesche Attribute:

Die Anwesenheit eines booleschen Attributes an einem Element symbolisiert den Wahr-Wert, die Abwesenheit des Attributs den Falsch-Wert.

Wenn der Wert des Attributs angegeben werden muss, obwohl es eigentlich nicht notwendig ist, folge diesem WhatWG Leitsatz:

Wenn das Attribut vorhanden ist, muss sein Wert entweder ein leerer String oder [...] der kanonische Name des Attributs ohne führendes oder nachgestelltes Leerzeichen sein.

Kurzgefasst: Füge keinen Wert hinzu.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Reduzierung des Markup

Wenn möglich, vermeide überflüssige Elternelemente beim Schreiben von HTML. Oft sind hierfür Code-Iterationen und Refactoring notwendig, aber letzendlich wird weniger HTML produziert, wie das Beispiel zeigt:

<!-- Nicht so gut -->
<span class="avatar">
  <img src="...">
</span>

<!-- Besser -->
<img class="avatar" src="...">

JavaScript generiertes Markup

Das Schreiben von Markup in JavaScript macht den Inhalt schwerer zu finden, schwerer zu editieren und weniger performant. Vermeide dies, wo möglich.

CSS

Syntax

Fragen bezüglich den hier verwendeten Begriffen? Weitere Informationen gibt es im Syntax Abschnitt des Cascading Style Sheet Artikels auf Wikipedia.

/* Schlechtes CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Gutes CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Reihenfolge der Deklarationen

Verbundene Eigenschaftsdeklarationen sollten in der folgenden Reihenfolge gruppiert werden:

  1. Positionierung
  2. Box Modell
  3. Typographie
  4. Aussehen

Positionierung kommt an erster Stelle, da es ein Element aus der normalen Verarbeitung eines Dokuments entfernen kann und Box Modell Styles überschreiben kann. Das Box Modell kommt als nächstes, da es die Größe und Platzierung der Komponente bestimmt.

Alles andere kommt hinterher, da es die Komponente im Inneren gestaltet, ohne die vorherigen beiden Sektionen zu beeinflussen

Eine komplette Liste der Eigenschaften und ihrer Reihenfolge kann bei Recess gefunden werden.

.declaration-order {
  /* Positionierung */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Boxmodell */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typographie */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Aussehen */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Anderes */
  opacity: 1;
}

Vermeide @import

Verglichen mit <link>s ist @import langsamer, führt zu mehr Seitenanforderungen und kann andere unvorhergesehene Probleme verursachen. Vermeide es und benutze stattdessen andere Ansätze:

Weitere Informationen finden sich in einem Artikel von Steve Souders.

<!-- Verwende link-Elemente -->
<link rel="stylesheet" href="core.css">

<!-- Vermeide @imports -->
<style>
  @import url("more.css");
</style>

Platzierung von Medienabfragen

Medienabfragen sollten so nahe wie möglich an den für sie relevanten Regeln platziert werden. Bündle sie nicht alle in einem separaten Stylesheet oder am Ende des Dokuments, andernfalls ist es einfach für andere, sie in Zukunft zu übersehen. Hier ist eine typische Deklaration.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Vorbestimmte Eigenschaften

Wenn herstellervorbestimmte Eigenschaften verwendet werden, rücke jede Eigenschaft so ein, dass die Deklarationswerte genau untereinander stehen, damit sie einfach bearbeitet werden können.

In Textmate, drücke Text → Edit Each Line in Selection (⌃⌘A). In Sublime Text 2, drücke Selection → Add Previous Line (⌃⇧↑) und Selection → Add Next Line (⌃⇧↓).

/* Praefixeigenschaften */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Einfache Deklarationen

In Fällen, in denen ein Regelsatz nur eine einzige Deklaration enthält, sollte der Zeilenumbruch für leichtere Lesbarkeit und schnelleres Editieren entfernt werden.

Der Punkt ist hier Fehlererkennung - z.B. ein CSS Validator, der aussagt, dass ein Syntax Error in Zeile 183 vorliegt. Mit einer einzigen Deklaration kann man ihn nicht verfehlen. Bei vielen Deklarationen sind separate Zeilen ein Muss.

/* Einzelne Deklarationen in einer Zeile */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Mehrere Deklarationen; eine pro Zeile */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Kurznotation

Bemühe dich, Kurznotationen nur in den Fällen zu benutzen, wo alle verfügbaren Werte explizit gesetzt werden müssen. Übermäßig benutzte Eigenschaften sind beispielsweise:

Oft müssen nicht alle Werte gesetzt werden, die eine Kurznotation repräsentiert. Zum Beispiel setzen HTML Überschriften nur den oberen und unteren margin, also müssen nur diese beiden Werte überschrieben werden, wenn es notwendig ist. Ausschweifende Benutzung von Kurznotation in Eigenschaften führt oft zu schlampigem Code mit unnötigen Überschreibungen und ungewollten Nebeneffekten.

Im Mozilla Entwicklernetzwerk gibt es einen großartigen Artikel über Kurznotationen für Eigenschaften für diejenigen, die mit Notationen und deren Verhalten nicht vertraut sind.

/* Schlechets Beispiel */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Gutes Beispiel */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Verschachtelung in Less und Sass

Vermeide unnötige Verschachtelungen. Nur weil verschachtelt werden kann, heißt das nicht, dass man es immer sollte. Berücksichtige Verschachtelung nur, wenn Styles im Elternelement gültig sein müssen und wenn mehrere Elemente zu verschachteln sind.

// Ohne Schachtelung
.table > thead > tr > th {  }
.table > thead > tr > td {  }

// Mit Schachtelung
.table > thead > tr {
  > th {  }
  > td {  }
}

Kommentare

Der Code wird von Menschen geschrieben und gepflegt. Stelle sicher, dass dein Code anschaulich, gut kommentiert und für andere zugänglich ist. Gute Kommentare vermitteln Kontext oder Zweck. Wiederhole nicht einfach den Komponenten- oder Klassennamen.

Stelle sicher, dass in längeren Kommentaren komplette Sätze geschrieben werden und kürze Sätze in generellen Anmerkungen.

/* Schlechtes Beispiel */
/* Modaler Header */
.modal-header {
  ...
}

/* Gutes Beispiel */
/* Umschliessendes Element fuer .modal-title und .modal-close */
.modal-header {
  ...
}

Klassennamen

Außerdem ist es hilfreich, viele dieser Regeln beizubehalten, wenn Sass und Less Variablennamen erstellt werden.

/* Schlechtes Beispiel */
.t { ... }
.red { ... }
.header { ... }

/* Gutes Beispiel */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selektoren

Weitere informationen:

/* Schlechtes Beispiel */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Gutes Beispiel */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Aufbau

/*
 * Komponentensektion Ueberschrift
 */

.element { ... }


/*
 * Komponentensektion &Uuml;berschrift
 *
 * Manchmal muss optionaler Kontext fuer die gesamte Komponente eingefuegt werden. Mache es so wie hier, wenn es wichtig ist.
 */

.element { ... }

/* Kontextuelle Subkomponente oder Attribut */
.element-heading { ... }

Editor Einstellungen

Stelle deinen Editor folgendermaßen ein, um verbreitete Inkonsistenzen und dirty diffs zu vermeiden:

Ziehe in Erwägung, diese Einstellungen in die .editorconfig-Datei deines Projektes zu schreiben. Für ein Beispiel, schaue dir diese Datei in Bootstrap an. Mehr über EditorConfig erfahren.