Standardi komentiranja

Jedinstvena pravila za komentare izvornog koda i dokumentacijske komentare.

• Dokumentiraj javne API-je; drži interne komentare minimalnima
• Preferiraj jasan kod nad komentarima
• Komentiraj samo neočito
• Standardni jezik: Engleski

Koristi za:

• Intent (namjera)
• Constraints (ograničenja)
• Trade-offs (kompromisi)
• Edge Cases (rubni slučajevi)

Izbjegavaj: Prepričavanje koda.

(* LOŠE - Prepričava kod *)
I := 0;  (* Postavi I na 0 *)
while I < Count do  (* Petlja dok je I manji od Count *)
begin
  ProcessItem(Items[I]);  (* Obradi Item *)
  Inc(I);  (* Povećaj I za 1 *)
end;
 
(* DOBRO - Objašnjava namjeru i ograničenje *)
(* 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]);

Za Pascal/FPC koristi se PasDoc-format.

(*
  @abstract(Kratki opis funkcije/klase)
 
  Opširni opis ako je potrebno.
  Objasni KADA i ZAŠTO se ova funkcija koristi.
 
  @param(APath Putanja do ulazne datoteke. Mora postojati.)
  @param(AOptions Opcionalne postavke obrade)
 
  @returns(True kod uspjeha, False kod validacijske greške)
 
  @raises(EFileNotFound ako APath ne postoji)
  @raises(EAccessDenied kod nedostatka dozvola)
 
  @seealso(ProcessDirectory za obradu direktorija)
 
  Security:
    - CWE-22: Putanja se validira protiv traversala
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

(*
  @abstract(DateEdit Control za unos datuma s Kalender-popupom)
 
  TWvdSDateEdit nudi polje za odabir datuma s:
  - Direktnim tekstualnim unosom s validacijom formata
  - Kalender-popupom za vizualni odabir
  - Validacijom raspona datuma (Min/Max)
 
  @bold(Uporaba:)
  - U formularima za unos datuma
  - Kao filter u pregledima podataka
  - Za odabir vremenskog raspona (od/do)
 
  @bold(Primjer:)
  @longcode(#
    DateEdit := TWvdSDateEdit.Create(Self);
    DateEdit.MinDate := EncodeDate(2000, 1, 1);
    DateEdit.MaxDate := Now;
    DateEdit.OnDateChanged := @HandleDateChanged;
  #)
 
  @seealso(TWvdSTimeEdit za odabir vremena)
  @seealso(TWvdSDateTimePicker za kombinirani odabir)
*)
TWvdSDateEdit = class(TWvdSCustomEdit)

(*
  @abstract(Validira unesenu vrijednost datuma)
 
  Provjerava je li uneseni datum:
  - U ispravnom formatu
  - Unutar MinDate/MaxDate
  - Validan datum (npr. ne 31. veljače)
 
  @param(AValue Vrijednost datuma za validaciju)
  @param(AError Poruka o grešci ako validacija ne uspije)
 
  @returns(True ako je datum validan, False kod greške)
 
  @note(Prazan unos smatra se validnim ako je AllowEmpty = True)
*)
function ValidateDate(const AValue: TDateTime;
  out AError: string): Boolean;

(*
  @abstract(Minimalni dopušteni datum)
 
  Postavlja najraniji datum koji se može odabrati.
  Unosi prije ovog datuma bit će odbijeni.
 
  @seealso(MaxDate za gornju granicu)
*)
property MinDate: TDateTime read FMinDate write SetMinDate;

[ ] Komentar objašnjava namjeru/trade-offs, ne mehaniku
[ ] Komentar odgovara trenutnom ponašanju (bez drifta)
[ ] Komentar je na engleskom i sažet
[ ] Javni API ima potpune doc-komentare
[ ] @param za svaki parametar prisutan
[ ] @returns za funkcije prisutan
[ ] @raises za moguće iznimke prisutan
[ ] Bez TODO/FIXME-komentara

• Javne API-je (obvezno)
• Neočite algoritme
• Workaround-e za poznate bugove
• Sigurnosno relevantne odluke
• Optimizacije performansi s trade-offs
• Vanjske ovisnosti

• Očit kod
• Samorazumljiv kod
• Privremeni debug-kod (treba ukloniti)
• Zakomentirani kod (treba obrisati)