# 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:

```python
# ==============================================================================
# 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:

```python
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:

```html
{# ==============================================================================
   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:

```html
{# 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
```javascript
/==============================================================================
 * Formeleon - Multi-tenant Form Generator
 * Author: Björn Runden <br@runden.net>
 * Script: <Script Name>
 * Description: <Zweck des Scripts>
 *============================================================================*/
```