====== Standard di Commento ======

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

===== Principi Base =====

<note tip>**I commenti spiegano PERCHE, non COSA.**</note>

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

===== Commenti Inline =====

Usa per:
  * Intent (Intenzione)
  * Constraints (Vincoli)
  * Trade-offs (Compromessi)
  * Edge Cases (Casi limite)

**Evita:** Raccontare il codice.

==== Esempio: Commenti Buoni vs. Cattivi ====

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

===== Commenti Doc (PasDoc) =====

Per Pascal/FPC si usa il formato **PasDoc**.

==== Struttura ====

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

==== Tag Obbligatori ====

^ Tag ^ Quando ^ Descrizione ^
| ''@abstract'' | Sempre | Breve descrizione su una riga |
| ''@param'' | Con parametri | Ogni parametro singolarmente |
| ''@returns'' | Con funzioni | Spiegare valore di ritorno |
| ''@raises'' | Con exception | Ogni possibile exception |

==== Tag Opzionali ====

^ Tag ^ Quando ^ Descrizione ^
| ''@seealso'' | Con funzioni correlate | Riferimenti incrociati |
| ''@deprecated'' | Con API obsolete | Indicare sostituto |
| ''@since'' | Con nuove API | Versione di introduzione |
| ''@note'' | Con note importanti | Attenzione particolare |
| ''@warning'' | Con insidie | Possibili problemi |

===== Documentazione Classi =====

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

===== Documentazione Metodi =====

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

===== Documentazione Property =====

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

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

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

===== Quando Commentare =====

==== Commentare ====

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

==== Non Commentare ====

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

===== Formati Specifici per Linguaggio =====

^ Linguaggio ^ Formato ^ Esempio ^
| Pascal/FPC | PasDoc | ''(* @abstract(...) *)'' |
| Delphi | XMLDoc-style | ''/// <summary>...</summary>'' |
| C# | XMLDoc | ''/// <summary>...</summary>'' |
| Rust | rustdoc | ''/// Descrizione'' |

===== Vedi anche =====

  * [[.:qualitaetssicherung|Panoramica Garanzia Qualità]]
  * [[.:code-konventionen|Convenzioni di Codice]]
  * [[.:audit-codequalitaet|Checklist Qualità Codice]]