86 lines
2.9 KiB
Markdown
86 lines
2.9 KiB
Markdown
# 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>
|
|
*============================================================================*/
|
|
``` |