Code-Guidelines
Auf dieser Seite
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 - ZHweb
Ist Ihnen etwas aufgefallen? Fehlt etwas? Möchten Sie etwas beitragen? Melden Sie sich bei uns!