Kommentierungsstandards

Einheitliche Regeln für Quellcode-Kommentare und Dokumentationskommentare.

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

Verwende für:

• Intent (Absicht)
• Constraints (Einschränkungen)
• Trade-offs (Kompromisse)
• Edge Cases (Randfälle)

Vermeide: Code nacherzählen.

(* 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]);

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

(*
  @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;

(*
  @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)

(*
  @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;

(*
  @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;

[ ] 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

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

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