Code-Konventionen

Verbindliche Coding-Standards für die WvdS FPC RAD Suite.

Microsoft-Stil Namespaces mit WvdS-Präfix:

WvdS.{Domain}.{Layer}.pas

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

Präfix nach Feature:

unit WvdS.{Feature}.{Layer};
 
{$mode objfpc}{$H+}
 
interface
 
uses
  // 1. System Units
  SysUtils, Classes,
  // 2. WvdS Common
  WvdS.System, WvdS.Collections,
  // 3. Feature-spezifisch
  WvdS.{Feature}.Models;
 
type
  // Typ-Definitionen
 
function PublicFunction(const AParam: string): Boolean;
procedure PublicProcedure(AValue: Integer);
 
implementation
 
uses
  // Private Uses (nur hier benötigte Units)
  WvdS.VSCode.Strings;
 
// Private Typen und Variablen
type
  TInternalHelper = class
  end;
 
var
  InternalState: TObject;
 
// Implementierungen
 
function PublicFunction(const AParam: string): Boolean;
begin
  // ...
end;
 
procedure PublicProcedure(AValue: Integer);
begin
  // ...
end;
 
initialization
  // Initialisierung
 
finalization
  // Aufräumen
 
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(Kurze Beschreibung in einem Satz.)
 
  Ausführliche Beschreibung des Zwecks und der Verwendung.
  Kann mehrere Sätze umfassen.
 
  @param(APath Vollständiger Pfad zur Datei)
  @param(AOptions Optionale Konfiguration, kann nil sein)
  @returns(True wenn erfolgreich, False bei Fehler)
 
  @raises(EWvdSFileNotFound wenn Datei nicht existiert)
  @raises(EWvdSAccessDenied wenn keine Leserechte)
 
  Security:
    - CWE-22: Pfad wird gegen Path Traversal validiert
 
  @seealso(RelatedFunction)
  @seealso(TWvdSRelatedClass)
*)
function ProcessFile(const APath: string; AOptions: TOptions): Boolean;

// Kurzer Kommentar für einzelne Zeile
Result := CalculateValue;
 
// Mehrzeiliger Kommentar für komplexere Logik
// Erklärt den Grund, nicht das Was
if (Value > Threshold) and (Mode = mAdvanced) then
begin
  // Wir müssen hier den erweiterten Algorithmus verwenden,
  // da der einfache bei großen Werten ungenau wird
  Result := AdvancedCalculation(Value);
end;

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

Konsistente Begriffe verwenden:

• 2 Spaces für Einrückung (nicht Tabs)
• begin auf eigener Zeile bei Blöcken
• end auf gleicher Einrückungsebene wie zugehöriges begin

// KORREKT
procedure Example;
begin
  if Condition then
  begin
    DoSomething;
    DoMore;
  end
  else
  begin
    DoAlternative;
  end;
end;
 
// VERBOTEN
procedure Example; begin
  if Condition then begin DoSomething; DoMore; end
  else DoAlternative;
end;

• Maximum 120 Zeichen pro Zeile
• Bei langen Ausdrücken umbrechen

// Bei langen Parameterlisten
function VeryLongFunctionName(
  const AFirstParameter: string;
  const ASecondParameter: Integer;
  AThirdParameter: TOptions
): Boolean;
 
// Bei langen Bedingungen
if (FirstCondition) and
   (SecondCondition) and
   (ThirdCondition) then
begin
  // ...
end;

// VERBOTEN
try
  DoSomething;
except
  // Nichts tun - Fehler verschlucken!
end;
 
// KORREKT
try
  DoSomething;
except
  on E: Exception do
    LogError(rsUnexpectedError, [E.ClassName, E.Message]);
end;

// VERBOTEN in main-Branch
// TODO: Implement this later
// FIXME: This is broken
 
// ERLAUBT nur in Feature-Branches, muß vor Merge entfernt werden

// VERBOTEN
ShowMessage('File not found');
ShowMessage('Datei nicht gefunden');
 
// KORREKT
ShowMessage(rsFileNotFound);  // resourcestring

// VERBOTEN
var
  GlobalConfig: TConfig;  // Schwer testbar!
 
// KORREKT - Parameter übergeben
function ProcessWithConfig(const AConfig: TConfig): Boolean;

Services müssen ohne VSCode/UI testbar sein:

// VERBOTEN - UI in Service
procedure ValidateAndShowError(const AName: string);
begin
  if not IsValid(AName) then
    ShowMessage('Invalid name');  // UI-Abhängigkeit!
end;
 
// KORREKT - Rückgabewert
function ValidateName(const AName: string; out AError: string): Boolean;
begin
  Result := IsValid(AName);
  if not Result then
    AError := rsInvalidName;
end;