====== Code-Konventionen ======

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

===== Namenskonventionen =====

==== Typen ====

^ Kategorie ^ Präfix ^ Beispiel ^
| Klasse | TWvdS* | TWvdSBuildConfig, TWvdSProjectManager |
| Interface | IWvdS* | IWvdSLogger, IWvdSParser |
| Record | TWvdS* | TWvdSBuildResult, TWvdSToolPath |
| Enum | TWvdS* | TWvdSProjectType, TWvdSBuildStatus |
| Exception | EWvdS* | EWvdSFileNotFound, EWvdSParseError |
| Callback | TWvdS* | TWvdSBuildCallback, TWvdSProgressHandler |

<note>Externe API-Typen (VSCode, Node.js) behalten ihre originalen Namen.</note>

==== Unit-Namen ====

Microsoft-Stil Namespaces mit WvdS-Präfix:

<code>
WvdS.{Domain}.{Layer}.pas

Beispiele:
WvdS.Build.Models.pas
WvdS.Build.Service.pas
WvdS.Projects.SettingsDialog.pas
WvdS.VSCode.Commands.pas
</code>

==== Layer-Suffixe ====

^ Suffix ^ Inhalt ^ Beispiel ^
| .Models | Records, Enums, Typen | WvdS.Build.Models |
| .Service | Geschäftslogik | WvdS.Build.Service |
| .Dialog | WebView-Dialoge | WvdS.Projects.SettingsDialog |
| .Provider | VSCode API Wrapper | WvdS.Designer.EditorProvider |

==== Variablen und Parameter ====

^ Kategorie ^ Präfix ^ Beispiel ^
| Private Felder | F | FProjectPath, FConfig |
| Parameter | A | APath, AOptions, ACallback |
| Lokale Variablen | Kein | Result, I, Config |

==== Resourcestrings ====

Präfix nach Feature:

^ Präfix ^ Feature ^
| rsCore* | Core Extension |
| rsBuild* | Build Extension |
| rsProject* | Projects Extension |
| rsDesigner* | UI Designer |
| rsPreview* | UI Preview |
| rsMeta* | UI Meta |
| rsPackaging* | Packaging |
| rsTool* | Toolchain |

===== Code-Struktur =====

==== Unit-Aufbau ====

<code pascal>
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.
</code>

==== Klassen-Aufbau ====

<code pascal>
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;
</code>

===== Dokumentation =====

==== PasDoc-Format ====

<code pascal>
(*
  @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;
</code>

==== Inline-Kommentare ====

<code pascal>
// 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;
</code>

===== Konstanten statt Magic Numbers =====

<code pascal>
// 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
</code>

===== Terminologie =====

Konsistente Begriffe verwenden:

^ Verwende ^ Vermeide ^
| Path | Url, Location, Dir (inkonsistent) |
| Config | Settings, Options, Prefs (inkonsistent) |
| Create | Make, Build (für Objekte) |
| Generate | Create (für Ausgabe) |
| Validate | Check, Verify (für Eingaben) |
| Initialize | Setup, Init (inkonsistent) |
| Execute | Run, Process (inkonsistent) |

===== Formatierung =====

==== Einrückung ====

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

<code pascal>
// 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;
</code>

==== Zeilenlänge ====

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

<code pascal>
// 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;
</code>

===== Verbotene Patterns =====

==== Leere Exception-Handler ====

<code pascal>
// VERBOTEN
try
  DoSomething;
except
  // Nichts tun - Fehler verschlucken!
end;

// KORREKT
try
  DoSomething;
except
  on E: Exception do
    LogError(rsUnexpectedError, [E.ClassName, E.Message]);
end;
</code>

==== TODO/FIXME im Produktionscode ====

<code pascal>
// VERBOTEN in main-Branch
// TODO: Implement this later
// FIXME: This is broken

// ERLAUBT nur in Feature-Branches, muß vor Merge entfernt werden
</code>

==== Hardcodierte Strings ====

<code pascal>
// VERBOTEN
ShowMessage('File not found');
ShowMessage('Datei nicht gefunden');

// KORREKT
ShowMessage(rsFileNotFound);  // resourcestring
</code>

==== Globale Variablen in Services ====

<code pascal>
// VERBOTEN
var
  GlobalConfig: TConfig;  // Schwer testbar!

// KORREKT - Parameter übergeben
function ProcessWithConfig(const AConfig: TConfig): Boolean;
</code>

===== Testbarkeit =====

Services müssen ohne VSCode/UI testbar sein:

<code pascal>
// 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;
</code>

===== pas2js Kompatibilität (WICHTIG) =====

<note warning>**pas2js ist NICHT 100% kompatibel mit FPC!** Diese Einschränkungen MÜSSEN beachtet werden.</note>

==== Nicht unterstützte Features ====

^ Feature ^ FPC ^ pas2js ^ Workaround ^
| ''class var'' | ✓ | ✗ | Unit-Level Variable verwenden |
| Inline ''var'' | ✓ | ✗ | Im ''var''-Block deklarieren |
| ''Int64'' | ✓ | ✗ | ''Integer'' verwenden |
| ''//'' in ''asm'' | ✓ | ✗ | ''/* */'' für JS-Kommentare |
| Lokale Var in ''asm'' | ✓ | ✗ | Direkt JS-Objekte verwenden |
| Konstanten in ''asm'' | ✓ | ✗ | Literal-Werte verwenden |
| ''-O2'' + asm-Aufrufe | ✓ | ✗ | ''-O-'' oder Methoden public machen |
| Unit-Funktion in ''asm'' | ✓ | ✗ | ''pas["Unit.Name"].FuncName()'' verwenden |
| ''out'' Param in ''asm'' | ✓ | ✗ | ''Param.set(value)'' verwenden |

==== Beispiele: Typen und Syntax ====

<code pascal>
(* VERBOTEN - class var *)
TMyClass = class
  class var FInstance: TMyClass;  (* pas2js Error! *)
end;

(* KORREKT - Unit-Level Variable *)
var
  GMyInstance: TMyClass = nil;

(* VERBOTEN - Inline var *)
begin
  var X := 42;  (* pas2js Error! *)
end;

(* KORREKT - var-Block *)
var
  X: Integer;
begin
  X := 42;
end;

(* VERBOTEN - Int64 *)
var
  Size: Int64;  (* pas2js: "Symbol Int64 is not implemented" *)

(* KORREKT - Integer *)
var
  Size: Integer;

(* VERBOTEN - // in asm *)
asm
  // JavaScript code  (* pas2js Error! *)
end;

(* KORREKT - /* */ in asm *)
asm
  /* JavaScript code */
end;
</code>

==== Beispiele: asm-Block Pitfalls ====

<note warning>Diese Fehler sind schwer zu finden, da sie erst zur Laufzeit auftreten!</note>

**Lokale Variablen sind NICHT in asm sichtbar:**

<code pascal>
(* VERBOTEN - Lokale Variable in asm *)
procedure Test;
var
  MyVar: TJSObject;
begin
  asm
    MyVar = {};  (* pas2js Error: MyVar is not defined! *)
  end;
end;

(* KORREKT - Direkt JS-Objekte verwenden *)
procedure Test;
begin
  asm
    module.exports.myFunc = function() {};  /* Direkt zugreifen */
  end;
end;
</code>

**Konstanten sind NICHT in asm sichtbar:**

<code pascal>
(* VERBOTEN - Konstante in asm *)
const
  TIMEOUT_MS = 5000;
begin
  asm
    setTimeout(func, TIMEOUT_MS);  (* pas2js Error: TIMEOUT_MS is not defined! *)
  end;
end;

(* KORREKT - Literal-Wert verwenden *)
begin
  asm
    setTimeout(func, 5000);  /* Literal statt Konstante */
  end;
end;
</code>

**Unit-Funktionen - NICHT mit Unterstrichen aufrufen:**

<code pascal>
(* VERBOTEN - self.* oder Unterstrich-Syntax *)
procedure TMyClass.HandleBrowse;
begin
  asm
    self.ToolchainConfig().DoSomething();  (* pas2js Error! *)
    pas.Toolchain_ConfigService.ToolchainConfig();  (* FALSCH: Unterstriche! *)
  end;
end;

(* KORREKT - pas["Unit.Name"].FuncName() Syntax *)
procedure TMyClass.HandleBrowse;
begin
  asm
    pas["Toolchain.ConfigService"].ToolchainConfig().DoSomething();  /* Richtig! */
  end;
end;
</code>

**out-Parameter - NICHT direkt zuweisen:**

<code pascal>
(* VERBOTEN - out-Parameter direkt zuweisen *)
function ValidateMessage(AMsg: TJSObject; out AType: string): Boolean;
begin
  asm
    AType = AMsg.type;  (* FALSCH: überschreibt getter/setter Objekt! *)
  end;
end;

(* KORREKT - out-Parameter mit .set() zuweisen *)
function ValidateMessage(AMsg: TJSObject; out AType: string): Boolean;
begin
  asm
    AType.set(AMsg.type);  /* RICHTIG: ruft den Setter auf */
  end;
end;
</code>

**-O2 Optimierung - kann asm-Aufrufe brechen:**

<code bash>
# PROBLEM: Bei -O2 werden private Methoden wegoptimiert
pas2js -O2 extension_main.pas  (* asm-Aufrufe können fehlschlagen *)

# LÖSUNG 1: Optimierung deaktivieren
pas2js -O- extension_main.pas

# LÖSUNG 2: Methoden public machen (nicht empfohlen)
</code>

==== Node.js API Pattern ====

**TNJ* Klassen sind KEINE Klassen** - sie sind Wrapper für Funktionen:

<code pascal>
(* VERBOTEN - Klassen-Methoden *)
Path := TNJPath.resolve(APath);           (* Error! *)
Exists := TNJFS.existsSync(APath);        (* Error! *)
Bytes := TNJCrypto.randomBytes(16);       (* Error! *)

(* KORREKT - Standalone Funktionen *)
uses NodeJS.Path, NodeJS.FS, NodeJS.Crypto;

Path := PathResolve([APath]);             (* Funktion aus NodeJS.Path *)
Exists := ExistsSync(APath);              (* Funktion aus NodeJS.FS *)
Bytes := RandomBytes(16);                 (* Funktion aus NodeJS.Crypto *)
</code>

==== TJSPromise Catch-Methode ====

<code pascal>
(* VERBOTEN - underscore catch *)
MyPromise._catch(ErrorHandler);  (* Funktioniert NICHT! *)

(* KORREKT - Punkt catch *)
MyPromise.catch(ErrorHandler);   (* So ist es richtig *)
</code>

==== Chained Bracket Access ====

pas2js erlaubt KEINE verketteten Bracket-Zugriffe auf JSValue:

<code pascal>
(* VERBOTEN - Verkettete Brackets *)
function GetStdout(RawResult: TJSObject): string;
begin
  asm
    Result = RawResult['stdout']['toString']();  (* pas2js Error! *)
  end;
end;

(* KORREKT - Zwischenvariable verwenden *)
function GetStdout(RawResult: TJSObject): string;
var
  StdoutObj: TJSObject;
begin
  StdoutObj := TJSObject(RawResult['stdout']);
  asm
    Result = StdoutObj['toString']();  /* Funktioniert */
  end;
end;
</code>

**Compiler-Fehler:** ''illegal qualifier "[" after "JSValue"''

==== Konstruktor-Signaturen beachten ====

Konstruktoren haben spezifische Signaturen - nicht raten:

<code pascal>
(* VERBOTEN - Falscher Parameter-Typ *)
var
  Channel: TOutputChannel;
  Logger: TWvdSLogger;
begin
  Channel := CreateOutputChannel('WvdS Projects');
  Logger := TWvdSLogger.Create(Channel);  (* Error: Got TOutputChannel, expected String *)
end;

(* KORREKT - Signatur prüfen *)
var
  Logger: TWvdSLogger;
begin
  Logger := TWvdSLogger.Create('wvds.projects');  (* Source-Name als String *)
end;
</code>

<note tip>Bei Compiler-Fehlern zu Parameter-Typen immer die Unit-Deklaration prüfen.</note>

==== Unit-Referenzen in asm-Blöcken ====

pas2js wandelt Punkte in Unterstriche:

<code pascal>
(* Pascal *)
uses WvdS.Build.Service;

(* In asm-Block *)
asm
  var service = pas.WvdS_Build_Service;  /* Unterstriche! */
end;
</code>

==== JavaScript-Interop ====

<code pascal>
(* asm-Block für direktes JavaScript *)
asm
  console.log('Direct JS call');
end;

(* Typisierte Variablen für JS-Objekte *)
var
  JsObj: TJSObject;
  JsArr: TJSArray;
</code>

==== Build-Konfiguration ====

Zwei Config-Dateien pro Extension:

**1. Shared Config** (''~/sources/common/wvds_common.pas2js.cfg''):
  * Compiler Mode, Target, Defines
  * RTL-Pfade, Common Unit-Pfade

**2. Extension-spezifische Config** (''build.cfg''):
  * Lokale Unit-Pfade (''-Fupas'')
  * Output-Pfad (''-FEdist/'', ''-odist/extension_main.js'')

Aufruf:
<code bash>
pas2js @../../common/wvds_common.pas2js.cfg @build.cfg pas/extension_main.pas
</code>

===== SSOT - Common Libraries verwenden =====

<note warning>**Direkte require()-Aufrufe sind VERBOTEN!** Immer die Pascal-Wrapper aus ''~/sources/common/'' verwenden.</note>

==== Node.js Wrappers ====

Verfügbar in ''~/sources/common/web/nodejs/'':

^ Unit ^ Zweck ^ Wichtige Funktionen ^
| ''NodeJS.Base'' | Core Node.js-Typen | TJSObject, RequireModule |
| ''NodeJS.FS'' | Dateisystem | ExistsSync, StatSync, ReadFileSync, WriteFileSync |
| ''NodeJS.Path'' | Pfadmanipulation | PathJoin, PathDirname, PathResolve, PathBasename |
| ''NodeJS.ChildProcess'' | Prozesse starten | Spawn, Exec, SpawnSync, TSpawnOptions |
| ''NodeJS.Crypto'' | Kryptographie | RandomBytes |
| ''NodeJS.Buffer'' | Binärdaten | TBuffer |

==== VSCode Wrappers ====

Verfügbar in ''~/sources/common/web/vscode/'':

^ Unit ^ Zweck ^ Wichtige Funktionen ^
| ''VSCode.Base'' | Core VSCode-Typen | TUri, TPosition, TRange, TTextDocument |
| ''VSCode.Window'' | Fenster-Operationen | ShowInformationMessage, CreateWebviewPanel |
| ''VSCode.Commands'' | Befehlsregistrierung | RegisterCommand, ExecuteCommand |
| ''VSCode.Workspace'' | Workspace-Operationen | FindFiles, GetConfiguration |
| ''VSCode.Tasks'' | Task-Ausführung | CreateShellTask, ExecuteTask |

==== WvdS Core System ====

Verfügbar in ''~/sources/common/core/system/'':

^ Unit ^ Zweck ^ Wichtige Funktionen ^
| ''WvdS.System.Logging'' | Unified Logging | TWvdSLogger, LogDebug, LogInfo, LogError |
| ''WvdS.VSCode.Security'' | Sicherheitsfunktionen | EscapeHtml, ValidateWebViewMessage, GetSecureNonce |
| ''WvdS.VSCode.Strings'' | Resourcestrings | 130+ lokalisierte Strings |
| ''WvdS.WebView.Bridge'' | Host-WebView Kommunikation | THostBridge, TBaseBridge |

==== SSOT-Refactoring Pattern ====

**Vorher (SSOT-Verletzung):**

<code pascal>
function IsFpcAvailable(const AFpcPath: string): Boolean;
begin
  asm
    try {
      var fs = require('fs');  /* VERBOTEN: direkter require! */
      Result = fs.existsSync(AFpcPath);
    } catch (e) {
      Result = false;
    }
  end;
end;
</code>

**Nachher (korrekt mit Common Library):**

<code pascal>
uses
  NodeJS.FS;  (* Wrapper aus common/ *)

function IsFpcAvailable(const AFpcPath: string): Boolean;
begin
  Result := ExistsSync(AFpcPath);  (* Pascal-Funktion *)
end;
</code>

==== Async File Operations ====

**Vorher (SSOT-Verletzung):**

<code pascal>
function LoadMetadata(const APath: string): TJSPromise;
begin
  asm
    Result = new Promise(function(resolve, reject) {
      var fs = require('fs');  /* VERBOTEN */
      fs.stat(APath, function(err, stats) { ... });
    });
  end;
end;
</code>

**Nachher (korrekt mit Common Library):**

<code pascal>
uses
  NodeJS.FS;

function LoadMetadata(const APath: string): TJSPromise;
begin
  Result := Stat(APath)._then(
    function(stats: JSValue): JSValue
    begin
      (* Verarbeite Stats *)
    end
  );
end;
</code>

===== Checkliste vor Commit =====

<code>
[ ] Namenskonventionen eingehalten
[ ] PasDoc-Dokumentation vorhanden
[ ] Keine Magic Numbers
[ ] Keine TODO/FIXME-Kommentare
[ ] Keine hardcodierten Strings
[ ] Keine leeren Exception-Handler
[ ] Keine globalen Variablen in Services
[ ] Keine UI-Abhängigkeiten in Services
[ ] Formatierung korrekt (Einrückung, Zeilenlänge)
[ ] Konsistente Terminologie
[ ] Common Libraries statt direkter require()
</code>

===== Siehe auch =====

  * [[.:sicherheit|Sicherheitsrichtlinien]]
  * [[.:i18n|Internationalisierung]]
  * [[.:extension-entwicklung|Extension-Entwicklung]]