Standard di Commento

Regole uniformi per commenti nel codice sorgente e commenti di documentazione.

• Documenta le API pubbliche; mantieni i commenti interni minimali
• Preferisci codice chiaro ai commenti
• Commenta solo ciò che non è ovvio
• Lingua standard: Inglese

Usa per:

• Intent (Intenzione)
• Constraints (Vincoli)
• Trade-offs (Compromessi)
• Edge Cases (Casi limite)

Evita: Raccontare il codice.

(* CATTIVO - Racconta il codice *)
I := 0;  (* Imposta I a 0 *)
while I < Count do  (* Cicla finché I è minore di Count *)
begin
  ProcessItem(Items[I]);  (* Elabora Item *)
  Inc(I);  (* Incrementa I di 1 *)
end;
 
(* BUONO - Spiega intenzione e vincolo *)
(* 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]);

Per Pascal/FPC si usa il formato PasDoc.

(*
  @abstract(Breve descrizione della funzione/classe)
 
  Descrizione dettagliata se necessario.
  Spiega QUANDO e PERCHE questa funzione viene usata.
 
  @param(APath Percorso al file di input. Deve esistere.)
  @param(AOptions Impostazioni di elaborazione opzionali)
 
  @returns(True in caso di successo, False in caso di errore di validazione)
 
  @raises(EFileNotFound se APath non esiste)
  @raises(EAccessDenied in caso di permessi mancanti)
 
  @seealso(ProcessDirectory per elaborazione directory)
 
  Security:
    - CWE-22: Il percorso viene validato contro traversal
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

(*
  @abstract(Control DateEdit per input date con popup calendario)
 
  TWvdSDateEdit offre un campo di input per selezione date con:
  - Input testo diretto con validazione formato
  - Popup calendario per selezione visiva
  - Validazione range date (Min/Max)
 
  @bold(Utilizzo:)
  - In form per input date
  - Come filtro in viste dati
  - Per selezione periodo (da/a)
 
  @bold(Esempio:)
  @longcode(#
    DateEdit := TWvdSDateEdit.Create(Self);
    DateEdit.MinDate := EncodeDate(2000, 1, 1);
    DateEdit.MaxDate := Now;
    DateEdit.OnDateChanged := @HandleDateChanged;
  #)
 
  @seealso(TWvdSTimeEdit per selezione ora)
  @seealso(TWvdSDateTimePicker per selezione combinata)
*)
TWvdSDateEdit = class(TWvdSCustomEdit)

(*
  @abstract(Valida il valore data inserito)
 
  Verifica se la data inserita:
  - E nel formato corretto
  - E compresa in MinDate/MaxDate
  - Rappresenta una data valida (es. nessun 31 febbraio)
 
  @param(AValue Il valore data da validare)
  @param(AError Messaggio di errore se la validazione fallisce)
 
  @returns(True se la data e valida, False in caso di errore)
 
  @note(Input vuoto e considerato valido se AllowEmpty = True)
*)
function ValidateDate(const AValue: TDateTime;
  out AError: string): Boolean;

(*
  @abstract(Data minima consentita)
 
  Imposta la data selezionabile piu antica.
  Gli input precedenti a questa data vengono rifiutati.
 
  @seealso(MaxDate per limite superiore)
*)
property MinDate: TDateTime read FMinDate write SetMinDate;

[ ] Il commento spiega Intent/Trade-offs, non la meccanica
[ ] Il commento corrisponde al comportamento attuale (nessun drift)
[ ] Il commento e in inglese e conciso
[ ] API pubblica ha commenti doc completi
[ ] @param per ogni parametro presente
[ ] @returns per funzioni presente
[ ] @raises per possibili exception presente
[ ] Nessun commento TODO/FIXME

• API pubbliche (Obbligatorio)
• Algoritmi non ovvi
• Workaround per bug noti
• Decisioni rilevanti per la sicurezza
• Ottimizzazioni performance con trade-off
• Dipendenze esterne

• Codice ovvio
• Codice auto-esplicativo
• Codice debug temporaneo (dovrebbe essere rimosso)
• Codice commentato (dovrebbe essere eliminato)