====== Standardi za komentiranje ======

Enotna pravila za komentarje v izvorni kodi in dokumentacijske komentarje.

===== Osnovna načela =====

<note tip>**Komentarji pojasnjujejo ZAKAJ, ne KAJ.**</note>

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

===== Vrstični komentarji =====

Uporabite za:
  * Intent (namen)
  * Constraints (omejitve)
  * Trade-offs (kompromisi)
  * Edge Cases (robni primeri)

**Izogibajte se:** Pripovedovanju kode.

==== Primer: Dobri vs. slabi komentarji ====

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

===== Dokumentacijski komentarji (PasDoc) =====

Za Pascal/FPC se uporablja format **PasDoc**.

==== Struktura ====

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

==== Obvezne oznake ====

^ Oznaka ^ Kdaj ^ Opis ^
| ''@abstract'' | Vedno | Enovrstični kratek opis |
| ''@param'' | Pri parametrih | Vsak parameter posebej |
| ''@returns'' | Pri funkcijah | Pojasnitev vrnjene vrednosti |
| ''@raises'' | Pri izjemah | Vsaka možna izjema |

==== Izbirne oznake ====

^ Oznaka ^ Kdaj ^ Opis ^
| ''@seealso'' | Pri sorodnih funkcijah | Navzkrižne reference |
| ''@deprecated'' | Pri zastarelih API-jih | Navedite zamenjavo |
| ''@since'' | Pri novih API-jih | Verzija uvedbe |
| ''@note'' | Pri pomembnih opombah | Posebna pozornost |
| ''@warning'' | Pri pasteh | Možne težave |

===== Dokumentacija razredov =====

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

===== Dokumentacija metod =====

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

===== Dokumentacija lastnosti =====

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

===== Kontrolni seznam za pregled =====

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

===== Kdaj komentirati =====

==== Komentirajte ====

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

==== Ne komentirajte ====

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

===== Formati glede na jezik =====

^ Jezik ^ Format ^ Primer ^
| Pascal/FPC | PasDoc | ''(* @abstract(...) *)'' |
| Delphi | XMLDoc-style | ''/// <summary>...</summary>'' |
| C# | XMLDoc | ''/// <summary>...</summary>'' |
| Rust | rustdoc | ''/// Opis'' |

===== Glejte tudi =====

  * [[.:qualitaetssicherung|Pregled zagotavljanja kakovosti]]
  * [[.:code-konventionen|Konvencije kode]]
  * [[.:audit-codequalitaet|Kontrolni seznam kakovosti kode]]