Code Conventions

Mandatory coding standards for the WvdS FPC RAD Suite.

Microsoft-style namespaces with WvdS prefix:

WvdS.{Domain}.{Layer}.pas

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

Prefix by feature:

unit WvdS.{Feature}.{Layer};
 
{$mode objfpc}{$H+}
 
interface
 
uses
  // 1. System Units
  SysUtils, Classes,
  // 2. WvdS Common
  WvdS.System, WvdS.Collections,
  // 3. Feature-specific
  WvdS.{Feature}.Models;
 
type
  // Type definitions
 
function PublicFunction(const AParam: string): Boolean;
procedure PublicProcedure(AValue: Integer);
 
implementation
 
uses
  // Private uses (units needed only here)
  WvdS.VSCode.Strings;
 
// Private types and variables
type
  TInternalHelper = class
  end;
 
var
  InternalState: TObject;
 
// Implementations
 
function PublicFunction(const AParam: string): Boolean;
begin
  // ...
end;
 
procedure PublicProcedure(AValue: Integer);
begin
  // ...
end;
 
initialization
  // Initialization
 
finalization
  // Cleanup
 
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(Short description in one sentence.)
 
  Detailed description of purpose and usage.
  Can span multiple sentences.
 
  @param(APath Full path to the file)
  @param(AOptions Optional configuration, can be nil)
  @returns(True if successful, False on error)
 
  @raises(EWvdSFileNotFound when file does not exist)
  @raises(EWvdSAccessDenied when no read permissions)
 
  Security:
    - CWE-22: Path is validated against path traversal
 
  @seealso(RelatedFunction)
  @seealso(TWvdSRelatedClass)
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

// Short comment for single line
Result := CalculateValue;
 
// Multi-line comment for more complex logic
// Explains the why, not the what
if (Value > Threshold) and (Mode = mAdvanced) then
begin
  // We need to use the advanced algorithm here,
  // as the simple one becomes inaccurate for large values
  Result := AdvancedCalculation(Value);
end;

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

Use consistent terms:

• 2 Spaces for indentation (not tabs)
• begin on its own line for blocks
• end at the same indentation level as the corresponding begin

// CORRECT
procedure Example;
begin
  if Condition then
  begin
    DoSomething;
    DoMore;
  end
  else
  begin
    DoAlternative;
  end;
end;
 
// FORBIDDEN
procedure Example; begin
  if Condition then begin DoSomething; DoMore; end
  else DoAlternative;
end;

• Maximum 120 characters per line
• Wrap long expressions

// For long parameter lists
function VeryLongFunctionName(
  const AFirstParameter: string;
  const ASecondParameter: Integer;
  AThirdParameter: TOptions
): Boolean;
 
// For long conditions
if (FirstCondition) and
   (SecondCondition) and
   (ThirdCondition) then
begin
  // ...
end;

// FORBIDDEN
try
  DoSomething;
except
  // Do nothing - swallowing errors!
end;
 
// CORRECT
try
  DoSomething;
except
  on E: Exception do
    LogError(rsUnexpectedError, [E.ClassName, E.Message]);
end;

// FORBIDDEN in main branch
// TODO: Implement this later
// FIXME: This is broken
 
// ALLOWED only in feature branches, must be removed before merge

// FORBIDDEN
ShowMessage('File not found');
ShowMessage('Datei nicht gefunden');
 
// CORRECT
ShowMessage(rsFileNotFound);  // resourcestring

// FORBIDDEN
var
  GlobalConfig: TConfig;  // Hard to test!
 
// CORRECT - Pass parameters
function ProcessWithConfig(const AConfig: TConfig): Boolean;

Services must be testable without VSCode/UI:

// FORBIDDEN - UI in Service
procedure ValidateAndShowError(const AName: string);
begin
  if not IsValid(AName) then
    ShowMessage('Invalid name');  // UI dependency!
end;
 
// CORRECT - Return value
function ValidateName(const AName: string; out AError: string): Boolean;
begin
  Result := IsValid(AName);
  if not Result then
    AError := rsInvalidName;
end;