ADR-003-HUMAN-READABLE-CODE-CONTRACTS

ADR-003 – Menschenlesbare Code-Verträge#

Status#

Accepted for MVP-001.

Kontext#

⌘ArtifactEin Artefakt ist jede eindeutig identifizierbare fachliche, technische, organisatorische oder reale Einheit, die in der Engineering-Landschaft modelliert wird. Manifests verbinden größere Implementierungsblöcke mit ⌘VisionEine Vision beschreibt eine langfristig gewünschte Wirkung und gibt der Weiterentwicklung eine gemeinsame Richtung., Capabilities, Requirements, Tests und Runtime. Diese maschinenlesbare Traceability erklärt jedoch nicht hinreichend, warum ein Modul oder ein fachlicher Use Case existiert und welche Invarianten er schützt.

Vollständige Kommentare jeder ⌘FunktionEin Feature ist eine abgegrenzte, nutzbare und lieferbare Ausprägung einer Lösung. würden den ⌘CodeCode ist eine ausführbare oder interpretierbare technische Realisierung, die durch Tests und Runtime-Evidence überprüfbar bleibt. überfrachten und rasch veralten. Fehlende fachliche Dokumentation erschwert dagegen Review, Wartung, Übergabe und die spätere Selbstdarstellung der Plattform.

Entscheidung#

Jeder größere Implementierungsblock und jeder fachlich relevante öffentliche Vertrag erhält einen Human-Readable Code Contract.

Der Contract besteht abgestuft aus:

1. einer Modulbeschreibung (doc.go oder Modul-README),
2. Dokumentation exportierter fachlicher Typen, Ports, Services und Methoden,
3. kurzen Use-Case-Dokumenten für zentrale Abläufe,
4. Verknüpfung dieser Dokumente im Artifact Manifest.

Private Hilfsfunktionen werden nur kommentiert, wenn das Warum, eine Invariante oder eine nicht offensichtliche technische Einschränkung erklärt werden muss.

Pflichtinhalte#

Ein Modulvertrag beschreibt mindestens:

• Zweck und fachliche ⌘HerkunftProvenienz beschreibt die nachvollziehbare Herkunft eines Wissenselements, einer Aussage oder einer abgeleiteten Darstellung.,
• Verantwortungen,
• ausdrückliche Ausschlüsse,
• geschützte Invarianten,
• öffentliche Ports und zentrale Use Cases,
• Verweis auf das Artifact Manifest.

Ein Use-Case-Vertrag beschreibt mindestens:

• Zweck,
• Auslöser,
• Voraussetzungen,
• Ablauf auf fachlicher Ebene,
• Ergebnis und Nebenwirkungen,
• relevante Fehlerfälle,
• Berechtigungen,
• Tests und Traceability.

Konsequenzen#

• Kommentare erklären fachliche Absicht und nicht die Syntax.
• Code, Dokumentation und Tests werden auf Modulebene validierbar verbunden.
• Die Workbench kann später Modul- und Use-Case-Dokumentation importieren und darstellen.
• Änderungen an Verantwortung oder öffentlichem Vertrag erfordern eine Aktualisierung von Manifest und Human-Readable Contract.
• Es entsteht keine Pflicht zur Dokumentation jeder privaten Funktion.

Beziehungen#

• ◆Modell für menschenlesbare Code-VerträgeTechnical documentation artifact. — constrains