Richtlinien für die Dokumentation im Quellcode. Um Sprachbarrieren und "Denglisch" zu vermeiden, werden alle Kommentare in den Quellcodedateien (PHP, JS, CSS) ausnahmslos auf Englisch verfasst. Ausnahme sind Übersetzungen für den Endnutzer, die müssen für Muttersprachler angenehm zu lesen sein und voll ausgeschrieben werden mit allen Besonderheiten, wie im Deutschen mit den Umlauten, mit Ausnahme des altmodischen Doppel-S ß, das wird immer als "ss" geschrieben.
Verwendung von strukturierten Doc-Blocks für Dateien, Klassen und Funktionen:
Datei-Header (File Header)
Hinweis: Verwendung von strukturierten Doc-Blocks. Beim Tag @module werden 1-3 prägnante englische Schlüsselbegriffe hinterlegt, die den genauen Kontext oder Bereich beschreiben wie [Dateiname, Bereich im Projekt, Funktionalität, Kontext, zum Beispiel eine Konfigurationsdatei für den Artikel-Editor: "Article editor config"].
Hinweis: Die Funktion kann mit ihrem Namen und oder ein paar Schlüsselbegriffen beschrieben werden. Optional kann eine kurze Beschreibung der Funktion folgen. Die Parameter werden mit Typ, Name (mit $ nur im PHP) und Beschreibung angegeben, nur falls vorhanden angegeben. Der Rückgabewert wird immer angegeben.
/**
* @function: Name and/or keywords
* @description: Optional description of the function
*
* @param type $name: Description of the parameter (if present)
* @param type $anotherName: Additional parameter description
* @return: Return type(s) or void for empty/no return
*/
Klassen-Header
/**
* @class: Name
* @association: Direct connections like parent, child, etc. (if present)
* @description: Core purpose and description of the class
*/
Klassen-Methoden (Kompaktversion)
Hinweis: Die Parameter werden mit Typ, Name (mit $ nur im PHP) und Beschreibung angegeben, nur falls vorhanden angegeben. Der Rückgabewert wird immer angegeben.
/** Short description / keywords
* @cfunc: optional keywords
* @param type $name: Parameter description (if present)
* @return: Return type or void */
Inline-Kommentare (Logik im Code)
Hinweis: Inline-Kommentare werden nur bei wirklichem Bedarf für kurze Erklärungen verwendet, die man nicht direkt am Code abliest, oder für die Strukturierung bei besonderen Fällen. Ein sauber strukturierter Code mit dem „Self-Documenting Code“ Prinzip steht immer im Vordergrund.
// Single-line comment for simple logic steps
/* Multi-line comment block used when a more
detailed architectural explanation is required */
CSS Dokumentation & Strukturierung
Stylesheets werden optisch klar strukturiert, um die Lesbarkeit zu maximieren:
Standardisierte Code-Kommentierung
Richtlinien für die Dokumentation im Quellcode. Um Sprachbarrieren und "Denglisch" zu vermeiden, werden alle Kommentare in den Quellcodedateien (PHP, JS, CSS) ausnahmslos auf Englisch verfasst. Ausnahme sind Übersetzungen für den Endnutzer, die müssen für Muttersprachler angenehm zu lesen sein und voll ausgeschrieben werden mit allen Besonderheiten, wie im Deutschen mit den Umlauten, mit Ausnahme des altmodischen Doppel-S ß, das wird immer als "ss" geschrieben.
🗺️ Stufe 0 | 📚 Actuell | 📟 2026 07 11 | 📍 Entwicklung
PHP & JavaScript Dokumentation
Verwendung von strukturierten Doc-Blocks für Dateien, Klassen und Funktionen:
Datei-Header (File Header)
Hinweis: Verwendung von strukturierten Doc-Blocks. Beim Tag @module werden 1-3 prägnante englische Schlüsselbegriffe hinterlegt, die den genauen Kontext oder Bereich beschreiben wie [Dateiname, Bereich im Projekt, Funktionalität, Kontext, zum Beispiel eine Konfigurationsdatei für den Artikel-Editor: "Article editor config"].
Funktions-Header
Hinweis: Die Funktion kann mit ihrem Namen und oder ein paar Schlüsselbegriffen beschrieben werden. Optional kann eine kurze Beschreibung der Funktion folgen. Die Parameter werden mit Typ, Name (mit $ nur im PHP) und Beschreibung angegeben, nur falls vorhanden angegeben. Der Rückgabewert wird immer angegeben.
Klassen-Header
Klassen-Methoden (Kompaktversion)
Hinweis: Die Parameter werden mit Typ, Name (mit $ nur im PHP) und Beschreibung angegeben, nur falls vorhanden angegeben. Der Rückgabewert wird immer angegeben.
Inline-Kommentare (Logik im Code)
Hinweis: Inline-Kommentare werden nur bei wirklichem Bedarf für kurze Erklärungen verwendet, die man nicht direkt am Code abliest, oder für die Strukturierung bei besonderen Fällen. Ein sauber strukturierter Code mit dem „Self-Documenting Code“ Prinzip steht immer im Vordergrund.
CSS Dokumentation & Strukturierung
Stylesheets werden optisch klar strukturiert, um die Lesbarkeit zu maximieren:
CSS Datei-Header
Hauptabschnitt (Section)
Unterabschnitt (Subsection)