Kodne konvencije

Obvezujoči standardi kodiranja za WvdS FPC RAD Suite.

Microsoftov stil imenskih prostorov s predpono WvdS:

WvdS.{Domena}.{Plast}.pas

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

Predpona po funkcionalnosti:

unit WvdS.{Feature}.{Layer};
 
{$mode objfpc}{$H+}
 
interface
 
uses
  // 1. Sistemske enote
  SysUtils, Classes,
  // 2. WvdS Common
  WvdS.System, WvdS.Collections,
  // 3. Funkcionalnostno specifične
  WvdS.{Feature}.Models;
 
type
  // Definicije tipov
 
function PublicFunction(const AParam: string): Boolean;
procedure PublicProcedure(AValue: Integer);
 
implementation
 
uses
  // Zasebni Uses (enote potrebne samo tukaj)
  WvdS.VSCode.Strings;
 
// Zasebni tipi in spremenljivke
type
  TInternalHelper = class
  end;
 
var
  InternalState: TObject;
 
// Implementacije
 
function PublicFunction(const AParam: string): Boolean;
begin
  // ...
end;
 
procedure PublicProcedure(AValue: Integer);
begin
  // ...
end;
 
initialization
  // Inicializacija
 
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(Kratek opis v enem stavku.)
 
  Podroben opis namena in uporabe.
  Lahko obsega več stavkov.
 
  @param(APath Polna pot do datoteke)
  @param(AOptions Opcijska konfiguracija, lahko nil)
  @returns(True če uspešno, False pri napaki)
 
  @raises(EWvdSFileNotFound če datoteka ne obstaja)
  @raises(EWvdSAccessDenied če ni pravic za branje)
 
  Varnost:
    - CWE-22: Pot se validira proti Path Traversal
 
  @seealso(RelatedFunction)
  @seealso(TWvdSRelatedClass)
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

// Kratek komentar za posamezno vrstico
Result := CalculateValue;
 
// Večvrstični komentar za kompleksnejšo logiko
// Razlaga razlog, ne kaj
if (Value > Threshold) and (Mode = mAdvanced) then
begin
  // Tukaj moramo uporabiti napredni algoritem,
  // ker je preprost pri velikih vrednostih nenatančen
  Result := AdvancedCalculation(Value);
end;

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

Dosledno uporabljajte izraze:

• 2 presledka za zamik (ne tabulatorji)
• begin na svoji vrstici pri blokih
• end na isti ravni zamika kot pripadajoči begin

// PRAVILNO
procedure Example;
begin
  if Condition then
  begin
    DoSomething;
    DoMore;
  end
  else
  begin
    DoAlternative;
  end;
end;
 
// PREPOVEDANO
procedure Example; begin
  if Condition then begin DoSomething; DoMore; end
  else DoAlternative;
end;

• Največ 120 znakov na vrstico
• Pri dolgih izrazih prelomite

// Pri dolgih seznamih parametrov
function VeryLongFunctionName(
  const AFirstParameter: string;
  const ASecondParameter: Integer;
  AThirdParameter: TOptions
): Boolean;
 
// Pri dolgih pogojih
if (FirstCondition) and
   (SecondCondition) and
   (ThirdCondition) then
begin
  // ...
end;

// PREPOVEDANO
try
  DoSomething;
except
  // Nič ne stori - napaka se potlači!
end;
 
// PRAVILNO
try
  DoSomething;
except
  on E: Exception do
    LogError(rsUnexpectedError, [E.ClassName, E.Message]);
end;

// PREPOVEDANO v main veji
// TODO: Implement this later
// FIXME: This is broken
 
// DOVOLJENO samo v vejah funkcionalnosti, mora biti odstranjeno pred združitvijo

// PREPOVEDANO
ShowMessage('File not found');
ShowMessage('Datei nicht gefunden');
 
// PRAVILNO
ShowMessage(rsFileNotFound);  // resourcestring

// PREPOVEDANO
var
  GlobalConfig: TConfig;  // Težko testabilno!
 
// PRAVILNO - parameter predati
function ProcessWithConfig(const AConfig: TConfig): Boolean;

Storitve morajo biti testabilne brez VSCode/UI:

// PREPOVEDANO - UI v storitvi
procedure ValidateAndShowError(const AName: string);
begin
  if not IsValid(AName) then
    ShowMessage('Invalid name');  // UI odvisnost!
end;
 
// PRAVILNO - povratna vrednost
function ValidateName(const AName: string; out AError: string): Boolean;
begin
  Result := IsValid(AName);
  if not Result then
    AError := rsInvalidName;
end;