Coding Standards & Header-Spezifikation

Dieses Dokument definiert die Richtlinien für Dateiköpfe, Dokumentation und Code-Kommentare im Projekt Formeleon. Alle von KI-Agenten oder Entwicklern erstellten Quelltexte müssen diesen Vorgaben entsprechen.

1. Autor & Metadaten

Autor: Björn Runden (br@runden.net)
Sprache im Code: Englisch (Variablen, Funktionen, Modulnamen, Code-Kommentare).
Sprache der Dokumentation: Deutsch.

2. Python Dateiköpfe & PyDoc Standards

2.1 Datei-Header (`.py`)

Jede Python-Datei beginnt mit folgendem Header:

# ==============================================================================
# Formeleon - Multi-tenant Form Generator
# Author: Björn Runden <br@runden.net>
# Module: <Modulname / Pfad>
# Description: <Kurze Beschreibung des Moduls>
# ==============================================================================

2.2 PyDoc für Funktionen, Methoden & Klassen

Jede Klasse, Funktion und Methode MUSS über einen PyDoc-Docstring dokumentiert sein:

def validate_handshake_token(public_key: str, origin: str) -> bool:
    """
    Validates the client handshake request against the tenant registry.

    :param public_key: Public API key transmitted by the client snippet.
    :param origin: Origin/Referer header provided by the client request.
    :return: True if the request origin matches allowed domains for the tenant, False otherwise.
    """
    pass

3. Jinja2 & HTML Standards (`.j2`, `.html`)

3.1 Datei-Header

Jedes Jinja2-Template oder HTML-File beginnt mit einem Kommentar-Header:

{# ==============================================================================
   Formeleon - Multi-tenant Form Generator
   Author: Björn Runden <br@runden.net>
   Template: <Template Name>
   Description: <Zweck des Templates>
   ============================================================================== #}

3.2 Dokumentation von Jinja2-Logik

Einfache Variablenersetzungen ({{ user.name }}) benötigen keinen Kommentar. Logikführende Blöcke (Schleifen, Modale, Bedingungen, Makros) MÜSSEN dokumentiert werden:

{# Iterates over active form fields and renders the corresponding input control #}
{% for field in form_fields %}
    <div class="mb-3">
        {# Render dynamic field label #}
        <label for="{{ field.id }}" class="form-label">{{ field.label }}</label>
        <input type="{{ field.type }}" id="{{ field.id }}" name="{{ field.name }}" class="form-control">
    </div>
{% endfor %}

4. JavaScript / CSS Standards (`.js`, `.css`)

4.1 Datei-Header

/==============================================================================
 * Formeleon - Multi-tenant Form Generator
 * Author: Björn Runden <br@runden.net>
 * Script: <Script Name>
 * Description: <Zweck des Scripts>
 *============================================================================*/

2.9 KiB Raw Permalink Blame History