Standardi za komentiranje

Enotna pravila za komentarje v izvorni kodi in dokumentacijske komentarje.

• Dokumentirajte javne API-je; notranje komentarje ohranite minimalne
• Dajte prednost jasni kodi pred komentarji
• Komentirajte samo neočitno
• Standardni jezik: angleščina

Uporabite za:

• Intent (namen)
• Constraints (omejitve)
• Trade-offs (kompromisi)
• Edge Cases (robni primeri)

Izogibajte se: Pripovedovanju kode.

(* SLABO - Pripoveduje kodo *)
I := 0;  (* Nastavi I na 0 *)
while I < Count do  (* Zanka dokler je I manjši od Count *)
begin
  ProcessItem(Items[I]);  (* Obdelaj element *)
  Inc(I);  (* Povečaj I za 1 *)
end;
 
(* DOBRO - Pojasnjuje namen in omejitev *)
(* 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 se uporablja format PasDoc.

(*
  @abstract(Kratek opis funkcije/razreda)
 
  Podroben opis po potrebi.
  Pojasnite KDAJ in ZAKAJ se ta funkcija uporablja.
 
  @param(APath Pot do vhodne datoteke. Mora obstajati.)
  @param(AOptions Izbirne nastavitve obdelave)
 
  @returns(True ob uspehu, False ob napaki validacije)
 
  @raises(EFileNotFound kadar APath ne obstaja)
  @raises(EAccessDenied ob manjkajočih dovoljenjih)
 
  @seealso(ProcessDirectory za obdelavo imenikov)
 
  Security:
    - CWE-22: Pot je validirana proti prečkanju
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

(*
  @abstract(DateEdit Control za vnos datuma s pojavnim koledarjem)
 
  TWvdSDateEdit zagotavlja vnosno polje za izbiro datuma z:
  - Neposrednim tekstovnim vnosom z validacijo formata
  - Pojavnim koledarjem za vizualno izbiro
  - Validacijo datumskega območja (Min/Max)
 
  @bold(Uporaba:)
  - V obrazcih za vnos datuma
  - Kot filter v podatkovnih pogledih
  - Za izbiro obdobja (od/do)
 
  @bold(Primer:)
  @longcode(#
    DateEdit := TWvdSDateEdit.Create(Self);
    DateEdit.MinDate := EncodeDate(2000, 1, 1);
    DateEdit.MaxDate := Now;
    DateEdit.OnDateChanged := @HandleDateChanged;
  #)
 
  @seealso(TWvdSTimeEdit za izbiro časa)
  @seealso(TWvdSDateTimePicker za kombinirano izbiro)
*)
TWvdSDateEdit = class(TWvdSCustomEdit)

(*
  @abstract(Validira vneseno datumsko vrednost)
 
  Preveri, ali je vneseni datum:
  - V pravilnem formatu
  - Znotraj MinDate/MaxDate
  - Veljaven datum (npr. ni 31. februarja)
 
  @param(AValue Datumska vrednost za validacijo)
  @param(AError Sporočilo o napaki, če validacija ne uspe)
 
  @returns(True če je datum veljaven, False ob napaki)
 
  @note(Prazen vnos velja za veljavnega, če je AllowEmpty = True)
*)
function ValidateDate(const AValue: TDateTime;
  out AError: string): Boolean;

(*
  @abstract(Najmanjši dovoljeni datum)
 
  Določa najzgodnejši datum, ki ga je mogoče izbrati.
  Vnosi pred tem datumom so zavrnjeni.
 
  @seealso(MaxDate za zgornjo mejo)
*)
property MinDate: TDateTime read FMinDate write SetMinDate;

[ ] Komentar pojasnjuje namen/kompromise, ne mehanike
[ ] Komentar ustreza trenutnemu obnašanju (brez odstopanja)
[ ] Komentar je v angleščini in jedrnat
[ ] Javni API ima popolne dokumentacijske komentarje
[ ] @param za vsak parameter prisoten
[ ] @returns za funkcije prisoten
[ ] @raises za možne izjeme prisoten
[ ] Brez komentarjev TODO/FIXME

• Javne API-je (obvezno)
• Neočitne algoritme
• Obvode za znane hrošče
• Varnostno pomembne odločitve
• Optimizacije zmogljivosti s kompromisi
• Zunanje odvisnosti

• Očitne kode
• Samoumevne kode
• Začasne razhroščevalne kode (je treba odstraniti)
• Izkomentiranega kode (je treba izbrisati)