====== Commenting Standards ======

Uniform rules for source code comments and documentation comments.

===== Core Principles =====

<note tip>**Comments explain WHY, not WHAT.**</note>

  * Document public APIs; keep internal comments minimal
  * Prefer clear code over comments
  * Comment only the non-obvious
  * **Standard language: English**

===== Inline Comments =====

Use for:
  * Intent
  * Constraints
  * Trade-offs
  * Edge Cases

**Avoid:** Narrating code.

==== Example: Good vs. Bad Comments ====

<code pascal>
(* BAD - Narrates code *)
I := 0;  (* Set I to 0 *)
while I < Count do  (* Loop while I is less than Count *)
begin
  ProcessItem(Items[I]);  (* Process item *)
  Inc(I);  (* Increment I by 1 *)
end;

(* GOOD - Explains intent and 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 Comments (PasDoc) =====

For Pascal/FPC, **PasDoc** format is used.

==== Structure ====

<code pascal>
(*
  @abstract(Brief description of the function/class)

  Detailed description when necessary.
  Explain WHEN and WHY this function is used.

  @param(APath Path to the input file. Must exist.)
  @param(AOptions Optional processing settings)

  @returns(True on success, False on validation error)

  @raises(EFileNotFound if APath does not exist)
  @raises(EAccessDenied if permissions are missing)

  @seealso(ProcessDirectory for directory processing)

  Security:
    - CWE-22: Path is validated against traversal
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;
</code>

==== Required Tags ====

^ Tag ^ When ^ Description ^
| ''@abstract'' | Always | One-line brief description |
| ''@param'' | For parameters | Each parameter individually |
| ''@returns'' | For functions | Explain return value |
| ''@raises'' | For exceptions | Each possible exception |

==== Optional Tags ====

^ Tag ^ When ^ Description ^
| ''@seealso'' | For related functions | Cross-references |
| ''@deprecated'' | For obsolete APIs | Specify replacement |
| ''@since'' | For new APIs | Version of introduction |
| ''@note'' | For important notices | Special attention |
| ''@warning'' | For pitfalls | Potential problems |

===== Class Documentation =====

<code pascal>
(*
  @abstract(DateEdit Control for date input with calendar popup)

  TWvdSDateEdit provides an input field for date selection with:
  - Direct text input with format validation
  - Calendar popup for visual selection
  - Date range validation (Min/Max)

  @bold(Usage:)
  - In forms for date input
  - As filter in data views
  - For date range selection (from/to)

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

  @seealso(TWvdSTimeEdit for time selection)
  @seealso(TWvdSDateTimePicker for combined selection)
*)
TWvdSDateEdit = class(TWvdSCustomEdit)
</code>

===== Method Documentation =====

<code pascal>
(*
  @abstract(Validates the entered date value)

  Checks if the entered date:
  - Is in the correct format
  - Is within MinDate/MaxDate range
  - Represents a valid date (e.g., not February 31st)

  @param(AValue The date value to validate)
  @param(AError Error message if validation fails)

  @returns(True if date is valid, False on error)

  @note(Empty input is considered valid if AllowEmpty = True)
*)
function ValidateDate(const AValue: TDateTime;
  out AError: string): Boolean;
</code>

===== Property Documentation =====

<code pascal>
(*
  @abstract(Minimum allowed date)

  Sets the earliest selectable date.
  Inputs before this date will be rejected.

  @seealso(MaxDate for upper bound)
*)
property MinDate: TDateTime read FMinDate write SetMinDate;
</code>

===== Review Checklist =====

<code>
[ ] Comment explains intent/trade-offs, not mechanics
[ ] Comment matches current behavior (no drift)
[ ] Comment is in English and concise
[ ] Public API has complete doc comments
[ ] @param for every parameter present
[ ] @returns for functions present
[ ] @raises for possible exceptions present
[ ] No TODO/FIXME comments
</code>

===== When to Comment =====

==== Do Comment ====

  * Public APIs (required)
  * Non-obvious algorithms
  * Workarounds for known bugs
  * Security-relevant decisions
  * Performance optimizations with trade-offs
  * External dependencies

==== Do Not Comment ====

  * Obvious code
  * Self-explanatory code
  * Temporary debug code (should be removed)
  * Commented-out code (should be deleted)

===== Language-Specific Formats =====

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

===== See Also =====

  * [[.:qualitaetssicherung|Quality Assurance Overview]]
  * [[.:code-konventionen|Code Conventions]]
  * [[.:audit-codequalitaet|Code Quality Checklist]]