Coding Guidelines

TOC:

1. Prämissen
2. Editoreinstellungen
3. Kommentare
   • CSS/SCSS
   • HTML/Markup
4. Format
   • CSS
   • Präprozessoren (SASS)
   • HTML/Markup
5. Namenkonventionen

---

1. Prämissen

• Alle Regeln und Vorgaben dieses Guides sind verbindlich für alle beteiligten Entwickler.
• Ist nicht eindeutig, wie etwas zu deklarieren ist, wird Rücksprache mit den Teammitgliedern gehalten.

2. Editoreinstellungen

Die (meisten) Einstellungen gelten übergreifend für CSS wie auch HTML/Markup.

Grundsätzliche Einstellungen/Regeln:

• Für Zeileneinzüge werden Spaces genutzt.
• Die Einrückungsweite wird auf 2 gesetzt.
• Vermische niemals Leerzeichen mit Tabs.
• Die maximale Zeilenlänge wird auf 80 Zeichen begrenzt (nur (S)CSS).
• Deklarationen, die mehr Zeichen in einer Zeile beinhalten, werden niemals per Hand umgebrochen.

EditorConfig

Um den Code-Stil konsistent zu halten wird eine Datei genutzt, die Voreinstellungen für Texteditoren bereitstellt (.editorconfig). Dies gewährleistet, dass alle Teammitglieder mit einer identischen Konfiguration arbeiten und die Ansicht des Codes konsistent in allen Texteditoren bleibt. Damit der jeweilige Texteditor die Konfigurationsdatei interpretieren kann, müssen alle Teammitglieder ein entsprechendes Plugin installieren (EditorConfig Plugin Downloads).

3. Kommentare

Gut dokumentierter Code ist extrem wichtig. Beschreibe so ausführlich wie notwendig deinen Code, so dass andere verstehen können, was der Code kann und was ggf. nicht.

Grundsätzliche Regeln:

• Kommentare werden auf English verfasst.
• Kommentare werden in ganzen, beschreibenden Sätzen und korrekter Interpunktion verfasst.
• Kommentare werden immer oberhalb des dokumentierten Codes/Markup plaziert
• Zwischen Kommentar und dokumentierten Code/Markup wird 1 Leerzeile gesetzt.
• Ganze Kommentar/Code Blocks werden durch 2 Leerzeilen voneinander abgesetzt.

CSS/SCSS

Das Format von Kommentare richtet sich danach, ob der kommentierte Code allein der Inline Dokumentation dient oder für die Dokumentation im Living Style Guide relevant ist.

Kommentare für Inline Code Dokumentation

Kommentare werden im JavaDoc Format notiert.

Beispiel eines ausführlichen Kommentars:

/**
 * Einzeilige Kurzbeschreibung
 * 
 * Ausführliche Beschreibung, die detailiert die Aufgabe des Codes
 * erklärt. Links und Beispiel Markup sind oft hilfreich oder gar
 * notwendig. Variablen oder/und Klassennamen werden mit Backticks
 * versehen (Bsp. `.example`). Ist die Erläuterung einzelner Deklarationen
 * sinnvoll, werden sie explizit kommentiert.
 *
 * Example HTML:
 *
 * <ul class="example">
 *      <li></li>
 *      ...
 * </ul>
 *
 * 1. Remove list style and padding/margin
 * 2. Reset font size inherited from `.example`
 */

.example {
    list-style: none;
    padding: 0; /* 1 */
    margin: 0; /* 1 */

    li {
        font-size: 1rem; /* 2 */
    }
}

Oftmals ist die ausführliche Kommentierung einer Deklaration nicht notwendig, sondern soll nur den Kontext verdeutlichen. In diesen Fall wird ein einzeiliger Kommentar verwendet.

Beispiel eines einfachen Kommentars:

/* Status Klasse für Slider  */

.slider.is-hidden { 
	display: none;
}

Kommentare für die Dokumentation im Living Style Guide

Die Dokumentation von Sourcecode, der im Living Style Guide abgebildet werden soll, folgt etwas anderen Regeln. Der Living Style Guide wird mit dem Gem Hologram erstellt, dass bestimmte Konventionen in der Kommentierung erfordert.

in Arbeit...

HTML/Markup

Kommentare im Markup sollten generell sparsam verwendet werden, da diese nicht entfernt werden im Deployment und durch korrekte Editoreinstellung (Einzug) i.d.R. schnell erkannt werden kann, wo ein Element beginnt und wo es endet. Für das visuelle Erfassen von Zusammenhängen ist es dennoch sinnvoll, das Ende eines größeren Markup-Blocks durch einen Kommentar auszuzeichnen.

• Ein Kommentar beginnt mit einem Schrägstrich (Synomym für das Ende eines Blocks).
• Ist keine Klassendeklaration vorhanden, wird der Element-Name notiert.
• Hat das Element einen Klassennamen, wird dieser notiert.

<header>
    ...
</header> <!-- /header -->


<header class="banner">
    ...
</header> <!-- /.banner -->

4. Format

CSS

Grundsätzliche Regeln:

• Eine öffnende geschweifte Klammer wird in der gleichen Zeile wie der Selektor notiert.
• Setze einen einfachen Leerschritt zwischen Selektor und öffnender geschweiften Klammer.
• Eine schließende geschweifte Klammer einer Deklaration steht in eigener Zeile und gleichen Spalte wie der öffenende Selektor.
• Jeder Selektor in Selektorketten wird in einer eigenen Zeile notiert.
• Jede Deklaration wird mit einem Semikolon abgeschlossen.
• Setze zwischen Attribut und Wert einer Deklaration ein Leerzeichen (e.g. margin: 1em).
• Werte mit führender Null werden explizit ausgeschrieben (e.g. margin: 0.1em).
• Nutze ausschließlich HEX Angaben in Farbdeklarationen in der keine Transparenz erforderlich ist.
• Nutze ausschließlich das RGBA Farbmodell, wenn Transparenzen erforderlich sind.
• Nutze durchgehend Kleinschreibung und Shorthand Schreibweise bei HEX Angaben (e.g. #fff).
• Es werden ausschließlich doppelte Anführungzeichen genutzt.
• Attributewerte werden in Anführungszeichen gesetzt (e.g. input[type="text")).
• Nullwerte werden, soweit valide, ohne Maßeinheiten notiert (e.g. margin: 0)
• Nach Kommata, die Werte/Eigenschaften separieren, wird jeweils ein Leerzeichen gesetzt (e.g. font-family: helvetica, arial, sans-serif).
• Jeder Deklarationsblock wird durch 1 Leerzeile abgesetzt.

Beispiel der oben genannten Regeln:

.selektor-1,
.selektor-2 {
    display: block;
    margin: 0; 
    color: #fff;
    background-color: rgba(0, 0, 0, 0.5);
}

input[type="text"] {
    font-family: helvetica, arial, sans-serif;
    font-size: inherit;
}

Ausnahme:

• Besteht die Deklaration aus lediglich eines Attribut/Werte-Paars und ist Teil einer zusammenhängenden Gruppe von Deklarationen, werden selektor, geschweifte Klammer und die Attribut/Werte Deklaration jeweils in 1 Zeile notiert. Geschweifte Klammern und Deklaration werden durch einen Leerschritt voneinander abgesetzt.

Beispiel der oben genannten Regeln:

.u-text-align--left { text-align: left; }
.u-text-align--right { text-align: right; }
.u-text-align--center { text-align: center; }

Reihenfolge der Deklarationen

Deklarationen werden in Blöcken zusammenhängender Eigenschaften notiert.

• Jeder Eigenschaftsblock wird durch eine Leerzeile voneinander abgesetzt.
• Innerhalb der Eigenschaftblöcke folgt die Sortierung keiner stringenten Konvention, sondern orientiert sich nach sinnvoll gruppierbaren Eigenschaften (e.g. top: 0; left: 0; oder width: 1em; height: 1em etc.).
• Zwischen den einzelnen Eigenschaftsblöcken wird 1 Leerzeile gesetzt.

.selektor {
    /* Positionierung */
    position: relative;
    z-index: 1;
    top: 0;
    right: 0;

    /* Box Model */
    display: block;
    box-sizing: border-box;
    padding: 1em;
    margin: 1em;
    width: 10em;
    height: 10em; /* Zu vermeiden ;-) */
    overflow: hidden; 

    /* Sonstige Angaben */
    color: #fff;
    background-color: #000;
    font-family: helvetica, arial, sans-serif;
    font-size: inherit;
    text-align: left; 
}

Präprozessoren (SASS)

Der Einsatz von (hier) SASS erfordert weitere Regeln, die verbindlich sind.

• Verschachtelung (Nesting) ist nicht erlaubt.
• Ausnahme: Deklarationen, die Pseudo-Selektoren für das Elternelement referenzieren.
• Verschachtelte Deklaration werden vor und nach der Notation durch 1 Leerzeile von dem umgebenden Code abgesetzt.
• Die Erweiterung einer Deklaration (per @extend) ist nur mit SASS-Placeholdern zulässig.
• @extend, @include werden am Anfang einer Deklaration notiert (in dieser Reihenfolge).
• Notierungen von SASS eigenen Statements (@) werden mit 1 Leerzeile von nachfolgenden Deklarationen abgesetzt.
• Um Konflikte mit Dritt-Libraries zu vermeiden, werden eigene Mixins und Funktionen mit einem Namespace-Prefix deklariert (Wahl des Prefix projektabhängig; im Beispiel wird x- als Prefix für die Funktion calculate-context genutzt).

/* Verschachtelung mit Pseudo-Selektoren */
a {
  text-decoration: none;

  &:hover, &:active, &:focus {
    text-decoration: underline;
  }

}


/* BEM Notation */

// FALSCH
.component {
  .component__child {
    ...
  }
}

// RICHTIG
.component {
  ...
}
.component__child {
  ...
}


/* Einsatz von @extend */

// FALSCH
.selektor {
    @extend .button;
}

// RICHTIG
.selektor {
    @extend %button;
}


/* Plazierung/Reihenfolge von @extend/@include Direktiven */
.selektor {
    @extend %button;
    @include font-size(16px);

    width: x-calculate-context(64em);
    ...
}

HTML/Markup

Folgende Regeln gelten für die Notation von Klassen innerhalb des Markups und Abständen zwischen Markup-Blöcken.

• Der schließende Tag eines HTML-Elementes wird in der gleichen Zeile wie der öffnende Tag notiert.
• Nach dem öffnenden Tag eines HTML-Elementes werden die Inhalte in einer neuen Zeile begonnen. Ausnahmen sind Elemente, die keine weiteren Elemente enthalten (bspw. <a>).
• Attribute im Markup werden immer in doppelte Anführungszeichen gesetzt.

<div class="c-vehicle-list">
    <ul>
        <li>
            <a>...</a>
        </li>
    </ul>
</div>


<dl>
    <dt>Term</dt>
    <dd>Description</dd>

    <dt>Term</dt>
    <dd>
        <span>Description</span>
    </dd>
</dl>

• Bei Mehrfachzuweisungen von Klassen-Attributen, werden diese mit jeweils 2 Leerschritten voneinander abgesetzt. Dies ist sinnvoll, da ab einer bestimmten Zahl an Attributen die Übersichtlichkeit verloren geht.

<div class="btn  btn--small  btn--submit">

• Layoutrelevante Markup-Blöcke werden durch 3 Leerzeilen voneinander abgesetzt.

<header>
    ...
</header>


<main>
    ...


    <aside>
        ...
    </aside>
</main>


<footer>
    ...
</footer>

---

5. Namenkonventionen

...