Konvencije koda

Obavezni standardi kodiranja za WvdS FPC RAD Suite.

Microsoft-stil Namespaces s WvdS-prefiksom:

WvdS.{Domain}.{Layer}.pas

Primjeri:
WvdS.Build.Models.pas
WvdS.Build.Service.pas
WvdS.Projects.SettingsDialog.pas
WvdS.VSCode.Commands.pas

Prefiks prema značajci:

unit WvdS.{Feature}.{Layer};
 
{$mode objfpc}{$H+}
 
interface
 
uses
  // 1. System Units
  SysUtils, Classes,
  // 2. WvdS Common
  WvdS.System, WvdS.Collections,
  // 3. Feature-specifično
  WvdS.{Feature}.Models;
 
type
  // Definicije tipova
 
function PublicFunction(const AParam: string): Boolean;
procedure PublicProcedure(AValue: Integer);
 
implementation
 
uses
  // Private Uses (samo ovdje potrebne Units)
  WvdS.VSCode.Strings;
 
// Privatni tipovi i varijable
type
  TInternalHelper = class
  end;
 
var
  InternalState: TObject;
 
// Implementacije
 
function PublicFunction(const AParam: string): Boolean;
begin
  // ...
end;
 
procedure PublicProcedure(AValue: Integer);
begin
  // ...
end;
 
initialization
  // Inicijalizacija
 
finalization
  // Čišćenje
 
end.

type
  TWvdSExampleClass = class(TObject)
  private
    FName: string;
    FValue: Integer;
    procedure SetName(const AValue: string);
  protected
    procedure DoInternalWork; virtual;
  public
    constructor Create(const AName: string);
    destructor Destroy; override;
    procedure Execute;
    property Name: string read FName write SetName;
    property Value: Integer read FValue write FValue;
  end;

(*
  @abstract(Kratki opis u jednoj rečenici.)
 
  Detaljni opis svrhe i korištenja.
  Može sadržavati više rečenica.
 
  @param(APath Potpuna putanja do datoteke)
  @param(AOptions Opcionalna konfiguracija, može biti nil)
  @returns(True ako uspješno, False kod greške)
 
  @raises(EWvdSFileNotFound ako datoteka ne postoji)
  @raises(EWvdSAccessDenied ako nema prava čitanja)
 
  Security:
    - CWE-22: Putanja se validira protiv Path Traversal
 
  @seealso(RelatedFunction)
  @seealso(TWvdSRelatedClass)
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

// Kratki komentar za jednu liniju
Result := CalculateValue;
 
// Višelinijski komentar za složeniju logiku
// Objašnjava razlog, ne što
if (Value > Threshold) and (Mode = mAdvanced) then
begin
  // Moramo ovdje koristiti prošireni algoritam,
  // jer jednostavni nije točan kod velikih vrijednosti
  Result := AdvancedCalculation(Value);
end;

// ZABRANJENO
if Length(Name) > 64 then
if Timeout > 30000 then
 
// ISPRAVNO
const
  MAX_PROJECT_NAME_LENGTH = 64;
  DEFAULT_TIMEOUT_MS = 30000;
 
if Length(Name) > MAX_PROJECT_NAME_LENGTH then
if Timeout > DEFAULT_TIMEOUT_MS then

Koristite konzistentne pojmove:

• 2 razmaka za uvlačenje (ne tabovi)
• begin na vlastitoj liniji kod blokova
• end na istoj razini uvlačenja kao pripadajući begin

// ISPRAVNO
procedure Example;
begin
  if Condition then
  begin
    DoSomething;
    DoMore;
  end
  else
  begin
    DoAlternative;
  end;
end;
 
// ZABRANJENO
procedure Example; begin
  if Condition then begin DoSomething; DoMore; end
  else DoAlternative;
end;

• Maksimalno 120 znakova po liniji
• Prelom kod dugih izraza

// Kod dugih lista parametara
function VeryLongFunctionName(
  const AFirstParameter: string;
  const ASecondParameter: Integer;
  AThirdParameter: TOptions
): Boolean;
 
// Kod dugih uvjeta
if (FirstCondition) and
   (SecondCondition) and
   (ThirdCondition) then
begin
  // ...
end;

// ZABRANJENO
try
  DoSomething;
except
  // Ništa ne raditi - gutanje greške!
end;
 
// ISPRAVNO
try
  DoSomething;
except
  on E: Exception do
    LogError(rsUnexpectedError, [E.ClassName, E.Message]);
end;

// ZABRANJENO u main-Branchu
// TODO: Implement this later
// FIXME: This is broken
 
// DOZVOLJENO samo u Feature-Branchevima, mora se ukloniti prije Mergea

// ZABRANJENO
ShowMessage('File not found');
ShowMessage('Datei nicht gefunden');
 
// ISPRAVNO
ShowMessage(rsFileNotFound);  // resourcestring

// ZABRANJENO
var
  GlobalConfig: TConfig;  // Teško testabilno!
 
// ISPRAVNO - predavanje parametra
function ProcessWithConfig(const AConfig: TConfig): Boolean;

Servisi moraju biti testabilni bez VSCode/UI:

// ZABRANJENO - UI u Servisu
procedure ValidateAndShowError(const AName: string);
begin
  if not IsValid(AName) then
    ShowMessage('Invalid name');  // UI-ovisnost!
end;
 
// ISPRAVNO - povratna vrijednost
function ValidateName(const AName: string; out AError: string): Boolean;
begin
  Result := IsValid(AName);
  if not Result then
    AError := rsInvalidName;
end;