====== Kommentierungsstandards ======

Einheitliche Regeln für Quellcode-Kommentare und Dokumentationskommentare.

===== Grundprinzipien =====

<note tip>**Kommentare erklären WARUM, nicht WAS.**</note>

  * Dokumentiere öffentliche APIs; halte interne Kommentare minimal
  * Bevorzuge klaren Code über Kommentare
  * Kommentiere nur das Nicht-Offensichtliche
  * **Standardsprache: Englisch**

===== Inline-Kommentare =====

Verwende für:
  * Intent (Absicht)
  * Constraints (Einschränkungen)
  * Trade-offs (Kompromisse)
  * Edge Cases (Randfälle)

**Vermeide:** Code nacherzählen.

==== Beispiel: Gute vs. Schlechte Kommentare ====

<code pascal>
(* SCHLECHT - Erzählt Code nach *)
I := 0;  (* Setze I auf 0 *)
while I < Count do  (* Schleife solange I kleiner als Count *)
begin
  ProcessItem(Items[I]);  (* Verarbeite Item *)
  Inc(I);  (* Erhöhe I um 1 *)
end;

(* GUT - Erklärt Absicht und Constraint *)
(* Process items in reverse order to maintain dependency chain.
   Items may reference later items, so forward processing would fail. *)
for I := Count - 1 downto 0 do
  ProcessItem(Items[I]);
</code>

===== Doc-Kommentare (PasDoc) =====

Für Pascal/FPC wird **PasDoc**-Format verwendet.

==== Struktur ====

<code pascal>
(*
  @abstract(Kurzbeschreibung der Funktion/Klasse)

  Ausführliche Beschreibung wenn nötig.
  Erkläre WANN und WARUM diese Funktion verwendet wird.

  @param(APath Pfad zur Eingabedatei. Muss existieren.)
  @param(AOptions Optionale Verarbeitungseinstellungen)

  @returns(True bei Erfolg, False bei Validierungsfehler)

  @raises(EFileNotFound wenn APath nicht existiert)
  @raises(EAccessDenied bei fehlenden Berechtigungen)

  @seealso(ProcessDirectory für Verzeichnisverarbeitung)

  Security:
    - CWE-22: Pfad wird gegen Traversal validiert
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;
</code>

==== Pflicht-Tags ====

^ Tag ^ Wann ^ Beschreibung ^
| ''@abstract'' | Immer | Einzeilige Kurzbeschreibung |
| ''@param'' | Bei Parametern | Jeder Parameter einzeln |
| ''@returns'' | Bei Funktionen | Rückgabewert erklären |
| ''@raises'' | Bei Exceptions | Jede mögliche Exception |

==== Optionale Tags ====

^ Tag ^ Wann ^ Beschreibung ^
| ''@seealso'' | Bei verwandten Funktionen | Querverweise |
| ''@deprecated'' | Bei veralteten APIs | Ersatz angeben |
| ''@since'' | Bei neuen APIs | Version der Einführung |
| ''@note'' | Bei wichtigen Hinweisen | Besondere Beachtung |
| ''@warning'' | Bei Fallstricken | Mögliche Probleme |

===== Klassen-Dokumentation =====

<code pascal>
(*
  @abstract(DateEdit Control für Datums-Eingabe mit Kalender-Popup)

  TWvdSDateEdit bietet ein Eingabefeld für Datumsauswahl mit:
  - Direkter Texteingabe mit Format-Validierung
  - Kalender-Popup für visuelle Auswahl
  - Datums-Range-Validierung (Min/Max)

  @bold(Verwendung:)
  - In Formularen für Datumseingabe
  - Als Filter in Datenansichten
  - Für Zeitraum-Auswahl (von/bis)

  @bold(Beispiel:)
  @longcode(#
    DateEdit := TWvdSDateEdit.Create(Self);
    DateEdit.MinDate := EncodeDate(2000, 1, 1);
    DateEdit.MaxDate := Now;
    DateEdit.OnDateChanged := @HandleDateChanged;
  #)

  @seealso(TWvdSTimeEdit für Zeitauswahl)
  @seealso(TWvdSDateTimePicker für kombinierte Auswahl)
*)
TWvdSDateEdit = class(TWvdSCustomEdit)
</code>

===== Methoden-Dokumentation =====

<code pascal>
(*
  @abstract(Validiert den eingegebenen Datumswert)

  Prüft ob das eingegebene Datum:
  - Im korrekten Format ist
  - Innerhalb von MinDate/MaxDate liegt
  - Ein gültiges Datum darstellt (z.B. kein 31. Februar)

  @param(AValue Der zu validierende Datumswert)
  @param(AError Fehlermeldung wenn Validierung fehlschlägt)

  @returns(True wenn Datum gültig, False bei Fehler)

  @note(Leere Eingabe gilt als gültig wenn AllowEmpty = True)
*)
function ValidateDate(const AValue: TDateTime;
  out AError: string): Boolean;
</code>

===== Property-Dokumentation =====

<code pascal>
(*
  @abstract(Minimales erlaubtes Datum)

  Legt das früheste auswählbare Datum fest.
  Eingaben vor diesem Datum werden abgelehnt.

  @seealso(MaxDate für obere Grenze)
*)
property MinDate: TDateTime read FMinDate write SetMinDate;
</code>

===== Review-Checkliste =====

<code>
[ ] Kommentar erklärt Intent/Trade-offs, nicht Mechanik
[ ] Kommentar entspricht aktuellem Verhalten (kein Drift)
[ ] Kommentar ist in Englisch und prägnant
[ ] Öffentliche API hat vollständige Doc-Kommentare
[ ] @param für jeden Parameter vorhanden
[ ] @returns für Funktionen vorhanden
[ ] @raises für mögliche Exceptions vorhanden
[ ] Keine TODO/FIXME-Kommentare
</code>

===== Wann Kommentieren =====

==== Kommentieren ====

  * Öffentliche APIs (Pflicht)
  * Nicht-offensichtliche Algorithmen
  * Workarounds für bekannte Bugs
  * Sicherheits-relevante Entscheidungen
  * Performance-Optimierungen mit Trade-offs
  * Externe Abhängigkeiten

==== Nicht Kommentieren ====

  * Offensichtlicher Code
  * Selbsterklärender Code
  * Temporärer Debug-Code (sollte entfernt werden)
  * Auskommentierter Code (sollte gelöscht werden)

===== Sprach-spezifische Formate =====

^ Sprache ^ Format ^ Beispiel ^
| Pascal/FPC | PasDoc | ''(* @abstract(...) *)'' |
| Delphi | XMLDoc-style | ''/// <summary>...</summary>'' |
| C# | XMLDoc | ''/// <summary>...</summary>'' |
| Rust | rustdoc | ''/// Beschreibung'' |

===== Siehe auch =====

  * [[.:qualitaetssicherung|Qualitätssicherung Übersicht]]
  * [[.:code-konventionen|Code-Konventionen]]
  * [[.:audit-codequalitaet|Codequalität-Checkliste]]