====== Kontrolni seznam kakovosti kode ======

Preverjanja za konvencije poimenovanja, zasnovo funkcij, načelo DRY in SSOT.

<note>Ta kontrolni seznam dopolnjuje [[.:code-konventionen|Konvencije kode]] s konkretnimi kontrolnimi točkami.</note>

===== Konvencije poimenovanja =====

==== Vzorec imenskega prostora (MS stil) ====

<code>
[ ] Imena enot sledijo WvdS.<Kategorija>.<Komponenta>.pas
[ ] Zrcali strukturo Microsoft .NET s predpono WvdS.
[ ] Primer: WvdS.UI.Controls.Button, WvdS.System.Logging
</code>

==== Hierarhija razredov (Borland stil) ====

<code>
[ ] Abstraktna baza uporablja predpono TWvdSCustom*
[ ] Javna baza uporablja predpono TWvdSBase*
[ ] Konkretni razredi uporabljajo predpono TWvdS*
[ ] Vzorec: TWvdSCustomXxx -> TWvdSBaseXxx -> TUserXxx
</code>

==== Predpone tipov ====

^ Kategorija ^ Predpona ^ Primer ^
| Razredi | ''TWvdS*'' | ''TWvdSRouter'', ''TWvdSButton'' |
| Vmesniki | ''IWvdS*'' | ''IWvdSActionResult'', ''IWvdSBindable'' |
| Izjeme | ''EWvdS*'' | ''EWvdSRoutingException'' |
| Zapisi | ''TWvdS*'' | ''TWvdSBuildResult'' |
| Naštevanja | ''TWvdS*'' | ''TWvdSProjectType'' |
| Povratni klici | ''TWvdS*'' | ''TWvdSBuildCallback'' |

==== Splošno poimenovanje ====

<code>
[ ] Opisna imena (brez posameznih črk razen v zankah)
[ ] Brez okrajšav razen znanih (URL, HTTP, JSON)
[ ] Vmesniki imajo GUID za DI-vsebnik
[ ] Zasebna polja: predpona F* (FValue, FCount)
[ ] Parametri: predpona A* (AIndex, APath)
</code>

===== Zasnova funkcij =====

==== Smernice za velikost ====

<code>
[ ] 12-24 vrstic idealno
[ ] Največ 40 vrstic (nad tem razdeliti)
[ ] Največja globina gnezdenja: 3
</code>

==== Smernice za parametre ====

<code>
[ ] Največ 5-7 parametrov
[ ] Pri več parametrih: uporaba zapisa/razreda
[ ] Izbirni parametri na koncu
</code>

==== Enojna odgovornost ====

<code>
[ ] Vsaka funkcija ima ENO nalogo
[ ] Ime funkcije v celoti opisuje nalogo
[ ] Če je v imenu potreben "in" -> razdeliti
</code>

==== Poimenovanje z glagolom na začetku ====

<code>
[ ] Get* - Pridobi vrednost
[ ] Set* - Nastavi vrednost
[ ] Calculate* - Izvedi izračun
[ ] Process* - Izvedi obdelavo
[ ] Validate* - Izvedi validacijo
[ ] Create* - Ustvari objekt
[ ] Parse* - Razčleni vnos
[ ] Format* - Oblikuj izhod
</code>

===== Načelo DRY =====

<code>
[ ] Brez podvojenega kode (več kot 3 identične vrstice -> ekstrahirati)
[ ] Brez vzorcev kopiraj-prilepi
[ ] Skupna logika v pomožnih funkcijah
[ ] Konstante namesto ponavljajočih se literalov
</code>

==== Primer: Odprava kršitve DRY ====

<code pascal>
(* PREPOVEDANO - Podvojena koda *)
procedure ProcessUserA(const AUser: TUser);
begin
  if not ValidateEmail(AUser.Email) then
    raise EValidationError.Create('Invalid email');
  if Length(AUser.Name) > 64 then
    raise EValidationError.Create('Name too long');
  (* ... nadaljnja obdelava *)
end;

procedure ProcessUserB(const AUser: TUser);
begin
  if not ValidateEmail(AUser.Email) then
    raise EValidationError.Create('Invalid email');
  if Length(AUser.Name) > 64 then
    raise EValidationError.Create('Name too long');
  (* ... druga obdelava *)
end;

(* PRAVILNO - Skupna logika ekstrahirana *)
procedure ValidateUser(const AUser: TUser);
begin
  if not ValidateEmail(AUser.Email) then
    raise EValidationError.Create(rsInvalidEmail);
  if Length(AUser.Name) > MAX_NAME_LENGTH then
    raise EValidationError.Create(rsNameTooLong);
end;

procedure ProcessUserA(const AUser: TUser);
begin
  ValidateUser(AUser);
  (* ... nadaljnja obdelava *)
end;
</code>

===== Preverjanje SSOT =====

<note warning>**Single Source of Truth** - Brez lokalnih kopij Common kode!</note>

==== Uporaba skupnih knjižnic ====

<code>
[ ] NodeJS-API-ji prek ~/sources/common/web/nodejs/
    - NodeJS.FS, NodeJS.Path, NodeJS.ChildProcess
[ ] VSCode-API-ji prek ~/sources/common/web/vscode/
    - VSCode.Window, VSCode.Commands, VSCode.Workspace
[ ] WvdS Core prek ~/sources/common/core/
    - WvdS.System.Logging, WvdS.VSCode.Security
</code>

==== Prepovedano ====

<code>
[ ] Brez neposrednih klicev require() v razširitvah
[ ] Brez dvojnikov Common-enot v razširitvah
[ ] Brez lokalnih implementacij ovojnic
</code>

==== Primer: Kršitev SSOT ====

<code pascal>
(* PREPOVEDANO - Lokalni require() *)
function FileExists(const APath: string): Boolean;
begin
  asm
    var fs = require('fs');  (* Kršitev SSOT! *)
    Result = fs.existsSync(APath);
  end;
end;

(* PRAVILNO - Skupna knjižnica *)
uses
  NodeJS.FS;

function FileExists(const APath: string): Boolean;
begin
  Result := ExistsSync(APath);  (* Iz NodeJS.FS *)
end;
</code>

===== Ločevanje odgovornosti =====

<code>
[ ] Logika UI samo v plasti UI (extension_main, *Dialog)
[ ] Poslovna logika samo v storitveni plasti (*Service)
[ ] Podatkovne strukture samo v modelni plasti (*Models)
[ ] Storitve ne kličejo VSCode-API-jev neposredno
[ ] Modeli ne vsebujejo logike
</code>

==== Arhitektura plasti ====

<code>
+-------------------------------------------------+
|  Plast UI (extension_main.pas, *Dialog.pas)     |
|  -> VSCode API-ji, interakcija z uporabnikom    |
+-------------------------------------------------+
|  Storitvena plast (*Service.pas)                |
|  -> Poslovna logika, validacija                 |
+-------------------------------------------------+
|  Modelna plast (*Models.pas)                    |
|  -> Zapisi, tipi, naštevanja                    |
+-------------------------------------------------+
|  Infrastruktura (NodeJS.*, VSCode.*, WvdS.*)    |
|  -> Zunanji API-ji, abstrakcija platforme       |
+-------------------------------------------------+
</code>

===== Hitri kontrolni seznam za kopiranje =====

<code>
Kontrolni seznam pregleda (kakovost kode):

Poimenovanje:
- [ ] Imena enot: WvdS.<Kategorija>.<Komponenta>.pas
- [ ] Razredi: predpona TWvdS*
- [ ] Vmesniki: predpona IWvdS*
- [ ] Opisna imena (brez okrajšav)

Funkcije:
- [ ] 12-24 vrstic idealno, največ 40
- [ ] Največ 5-7 parametrov
- [ ] Enojna odgovornost
- [ ] Poimenovanje z glagolom na začetku

DRY:
- [ ] Brez podvojenega kode
- [ ] Skupna logika ekstrahirana
- [ ] Konstante namesto literalov

SSOT:
- [ ] Skupne knjižnice uporabljene
- [ ] Brez lokalnih klicev require()
- [ ] Brez dvojnikov Common-enot

SoC:
- [ ] UI samo v plasti UI
- [ ] Logika samo v storitveni plasti
- [ ] Storitve brez neposrednih klicev VSCode
</code>

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

  * [[.:qualitaetssicherung|Pregled zagotavljanja kakovosti]]
  * [[.:code-konventionen|Konvencije kode]]
  * [[.:audit-core|Kontrolni seznam Core]]
  * [[.:extension-entwicklung|Razvoj razširitev]]