Code-Guidelines

Inhaltsverzeichnis

Hauptkapitel
Designsystem
Unterkapitel
Community - so können Sie beitragen
Gilt für
Websites & Webapplikationen (mit Login)

Allgemeine Grundsätze

Beim Schreiben von Quellcode steht die Lesbarkeit im Vordergrund. Damit andere Entwicklerinnen und Entwickler den Quellcode nachvollziehen können und einheitliche Formatierungen verwendet werden, halten wir uns an folgende Grundsätze:

Vorteile:

  • Schreibe Quellcode so konzis wie möglich.
  • Halte dich an die vorgegebenen Konventionen zur Benennung (Naming Conventions).
  • Gruppiere zusammengehörige Blöcke von Code mit einer Leerzeile dazwischen.
  • Verwende Encoding und Einrückungen gemäss der Definition in .editorconfig (UTF-8, 2 Leerschläge).
  • Beachte sprachspezifische Best Practices.

Untergliederung

Wir verwenden eine vereinfachte Form von Atomic Design.

Atome

Atome sind im Code des Design Systems nicht weiter teilbare Einheiten. Sie enthalten lediglich HTML und CSS, aber keine JavaScript-Logik.

Klassen für Atome erhalten das Block-Präfix «atm-».

Module

Module sind im Code des Design Systems zusammengesetzte Einheiten, die aus verschiedenen Atomen oder weiteren Modulen bestehen können.

Klassen für Module erhalten das Block-Präfix «mdl-».

Layouts

Layouts sind im Code des Design Systems das HTML-Grundgerüst einer Seite. Layouts enthalten kein eigenes CSS und keine JavaScript-Logik.

Klassen für Layouts erhalten das Block-Präfix «lyt-».

Seiten

Seiten sind Kollektionen von Modulen, die mit einem Layout zu einer vollständigen Seite gerendert werden.

Markup

Wir verwenden Handlebars Templates. Valides, semantisches HTML ist das oberste Gebot.

Naming Convention für Klassen

Wir verwenden BEM (Block, Element, Modifier) als Naming Convention:

  • Block / Blöcke: block
  • Element / Unterelemente in Blöcken: block__element
  • Modifier / Zustände, Darstellungsformen, Verhaltensweisen: block--modifier

Styles

Wir verwenden Sass mit SCSS Syntax.

Linting

Wir verwenden Stylelint gemäss dem in .stylelintrc.json definierten Regeln.

Scripts

Wir verwenden TypeScript.

Linting

Wir verwenden ESLint gemäss den in .eslintrc.json definierten Regeln (die an diejenigen von Airbnb angelehnt sind).

Typen

Wir benutzen TypeScript, um mit Typensicherheit in JavaScript zu arbeiten:

let isWinter: boolean = false;

Variablen

Wir vermeiden das Schlüsselwort 'var', um eine Variable zu deklarieren. Der Grund dafür ist, dass der Scope von 'var' die ganze Funktion und nicht nur der spezifische Block ist, für den eine Variable definiert wurde.

Statt dessen verwenden wir 'const', um Werte einer Variablen zuzuweisen, die nie geändert wird. Wenn der Wert der Variable geändert werden können muss, verwenden wir 'let'.

Wir bevorzugen 'const' gegenüber 'let', wenn sich eine Änderung des Variablenwerts vermeiden lässt (Principle of least privilege).

Kommentare

Wir halten uns an die Konventionen von JSDoc.

Bei Funktionen müssen mindestens die Parameter (@param) und Rückgabewerte (@returns) aufgeführt werden:

/**
* Logs message in console
* @param {string} message
* @returns {void}
*/
public myFunction(message: string): void {
console.log(message);
}

Deklaration und Reihenfolge von Methoden

Wir schreiben immer, ob Methoden 'public', 'protected' oder 'private' sind.

Öffentliche Methoden ('public') kommen immer zuerst, dann 'protected' und 'private' am Schluss.

Magic Numbers

Wenn Magic Numbers nötig sind, weisen wir sie stets einer Variablen ('const') mit einem sprechenden Namen zu.

Kontakt

Digitale Verwaltung und E-Government – ZHweb

Ist Ihnen etwas aufgefallen? Fehlt etwas? Möchten Sie etwas beitragen? Melden Sie sich bei uns!

Mehr erfahren