Commenting Standards

Uniform rules for source code comments and documentation comments.

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

Use for:

• Intent
• Constraints
• Trade-offs
• Edge Cases

Avoid: Narrating code.

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

For Pascal/FPC, PasDoc format is used.

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

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

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

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

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

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

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