====== Standardi komentiranja ======

Jedinstvena pravila za komentare izvornog koda i dokumentacijske komentare.

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

<note tip>**Komentari objašnjavaju ZAŠTO, ne ŠTO.**</note>

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

===== Inline-komentari =====

Koristi za:
  * Intent (namjera)
  * Constraints (ograničenja)
  * Trade-offs (kompromisi)
  * Edge Cases (rubni slučajevi)

**Izbjegavaj:** Prepričavanje koda.

==== Primjer: Dobri vs. Loši komentari ====

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

===== Doc-komentari (PasDoc) =====

Za Pascal/FPC koristi se **PasDoc**-format.

==== Struktura ====

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

==== Obvezni tagovi ====

^ Tag ^ Kada ^ Opis ^
| ''@abstract'' | Uvijek | Jednolinijski kratki opis |
| ''@param'' | Kod parametara | Svaki parametar pojedinačno |
| ''@returns'' | Kod funkcija | Objasni povratnu vrijednost |
| ''@raises'' | Kod iznimki | Svaka moguća iznimka |

==== Opcionalni tagovi ====

^ Tag ^ Kada ^ Opis ^
| ''@seealso'' | Kod povezanih funkcija | Unakrsne reference |
| ''@deprecated'' | Kod zastarjelih API-ja | Navedi zamjenu |
| ''@since'' | Kod novih API-ja | Verzija uvođenja |
| ''@note'' | Kod važnih napomena | Posebna pozornost |
| ''@warning'' | Kod zamki | Mogući problemi |

===== Dokumentacija klasa =====

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

===== Dokumentacija metoda =====

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

===== Dokumentacija svojstava =====

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

===== Kontrolna lista pregleda =====

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

===== Kada komentirati =====

==== Komentirati ====

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

==== Ne komentirati ====

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

===== Formati specifični za jezik =====

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

===== Vidi također =====

  * [[.:qualitaetssicherung|Pregled osiguranja kvalitete]]
  * [[.:code-konventionen|Konvencije koda]]
  * [[.:audit-codequalitaet|Kontrolna lista kvalitete koda]]