Coding Style¶

Diese Seite definiert den Basisstil für PCS-PLC-Quelldateien. Das Ziel ist einfach: Jeder Baustein soll leicht zu finden, leicht zu scannen und schwer falsch zu verwenden sein.

Goldene Regel

Namen sollen die Engineering-Absicht erklären. Leserinnen und Leser sollen verstehen, was ein Signal bedeutet, ohne die Implementierung durchsuchen zu müssen.

Kurze Regeln¶

Bereich	Regel
Bausteine	Verwende die Präfixe `FB_`, `FC_`, `OB_`, `DB_` oder `UDT_`.
Ablageort	Lege Sources unterhalb von `tia/exports` im verantwortlichen Subsystemordner ab.
Header	FB-, FC- und OB-Sources enthalten den Standard-Beschreibungsheader.
Variablen	Verwende Typpräfixe plus aussagekräftige Prozessnamen.
Booleans	Boolean-Namen müssen sich wie True/False-Aussagen lesen.
Einheiten	Ergänze Engineering-Einheiten im Namen, wenn Einheiten relevant sind.
Große Dateien	Verwende nummerierte `REGION`-Abschnitte.

Scaffold-Befehl nicht umgehen

Bevorzuge pcs new block ... für neue Sources. Der Befehl erstellt die richtige Dateiendung, das richtige Benennungsmuster und den Header. Manuell erstellte Dateien driften leicht ab.

Bausteinnamen¶

Bausteinnamen müssen mit einem der freigegebenen Präfixe beginnen:

Präfix	Objekttyp	Dateiendung	Beispiel
`FB_`	Function block	`.scl`	`FB_AlarmRouting`
`FC_`	Function	`.scl`	`FC_ClampReal`
`OB_`	Organization block	`.scl`	`OB1_MAIN_CYCLE`
`DB_`	Data block	`.db`	`DB_AlarmConfig`
`UDT_`	User data type	`.udt`	`UDT_AlarmEntry`

Neue Bausteine erstellen mit:

pcs new block 06_ALARMS/FB_AlarmRouting
pcs new block 06_ALARMS/UDT_AlarmEntry
pcs new block 00_SYSTEM/DB_SystemConfig

GutVermeiden

FB_PowerLimiter
FB_CommandArbitration
DB_PowerManagementState
UDT_PropulsionCommand

FB_Logic
FB_NewBlock
DB_Data
UDT_Struct1

Warum strikte Bausteinpräfixe wichtig sind

Das Präfix sagt jedem Engineer und jedem Tool, welcher TIA-Objekttyp erwartet wird. Es erlaubt pcs new block ... außerdem zu entscheiden, ob .scl, .db oder .udt erstellt werden soll.

Source-Ablageort¶

Sources liegen unterhalb von tia/exports und sind nach Subsystem oder Verantwortung gruppiert:

tia/exports/
  00_SYSTEM/
  01_PLATFORM/
  02_INTERFACES/
  06_ALARMS/
  99_LEGACY/

Verantwortung schlägt Dateityp

Halte zusammengehörige FBs, FCs, DBs und UDTs zusammen. Alarm-Logik gehört in 06_ALARMS, nicht aufgeteilt in separate technische Ordner für Bausteine und Datentypen.

Beschreibungsheader¶

FB-, FC- und OB-Sources enthalten einen konsistenten Beschreibungsheader. Der Header liegt innerhalb von BEGIN, damit er in TIA Portal sichtbar ist:

FUNCTION_BLOCK "FB_AlarmRouting"
{ S7_Optimized_Access := 'FALSE' }
VERSION : 0.1

BEGIN
REGION S000 - Description
(**************************************************************************************************
Function block: FB_AlarmRouting

---------------------------------------------------------------------------------------------------
Version  | Date       | Author             | Comment
---------------------------------------------------------------------------------------------------
v0.1.0   | 2026-05-09 | Tom Westerling     | Initial scaffold
---------------------------------------------------------------------------------------------------

Description:
Routes active alarms to the configured HMI and horn outputs.

**************************************************************************************************)
END_REGION

// Keep the logic boring. Keep the vessel safe.

END_FUNCTION_BLOCK

DB- und UDT-Sources enthalten bewusst keine Beschreibungsheader oder Inline-Kommentare. TIA-Source-Generierung round-tripped diese Kommentare nicht zuverlässig, deshalb folgen diese Dateien dem von TIA generierten Source-Stil, um falsche Sync-Unterschiede zu vermeiden.

Verwende das passende Objektlabel:

Objekt	Header-Label
`FB_`	`Function block:`
`FC_`	`Function:`
`OB_`	`Organization block:`

Tip

Der Befehl pcs new block ... erstellt den Header für SCL-Bausteine automatisch, einschließlich Datum, Autor, REGION S000 - Description und kleinem Scaffold-Kommentar.

DB- und UDT-Sources¶

DB- und UDT-Dateien sollen nahe an dem Source bleiben, den TIA Portal generiert:

DATA_BLOCK "DB_SystemConfig"
{ S7_Optimized_Access := 'FALSE' }
VERSION : 0.1
   STRUCT
      xboPlaceholder : Bool;
   END_STRUCT;

BEGIN

END_DATA_BLOCK

TYPE "UDT_LimitConfig"
VERSION : 0.1

   STRUCT
      xboPlaceholder : Bool;
   END_STRUCT;

END_TYPE

Regeln für DB- und UDT-Dateien:

Verwende STRUCT ... END_STRUCT;, nicht VAR ... END_VAR.
Keine Beschreibungsheader, Regionen, Blockkommentare oder Inline-Kommentare ergänzen.
Engineering-Erklärungen gehören in die Dokumentation oder in die SCL-Bausteine, die die Daten verwenden.
Nach Import in TIA und Snapshot-Export sollen DB-/UDT-Dateien keine reinen Kommentar- oder Formatierungsunterschiede erzeugen.

Regionen¶

Verwende REGION ... END_REGION, um logische Abschnitte in größeren Dateien zu trennen. S000 - Description ist für den generierten Header reserviert. Implementierungsregionen beginnen bei S001.

REGION S001 - Input parameter validation
    // Validate configured limits and command source.
END_REGION

REGION S002 - Diagnostics
    // Evaluate error states and status flags.
END_REGION

REGION S003 - Output assignment
    // Assign final output values.
END_REGION

Regionen nützlich halten

Bevorzuge wenige aussagekräftige Regionen gegenüber vielen winzigen. Ein kleiner Scaffold-Baustein braucht keine Regionen, bis die Logik wächst.

Variablennamen¶

Variablennamen sollen die Rolle des Werts im Prozess erklären. Das Typpräfix ist nur ein schneller Hinweis; der Rest des Namens trägt die Bedeutung.

GutVermeiden

xboStationCommandActive : Bool;
xboDriveFeedbackHealthy : Bool;
reRequestedShaftSpeedRpm : Real;
reAvailablePowerKw : Real;
timAlarmDelay : Time;
stPropulsionCommand : "UDT_PropulsionCommand";

x1 : Bool;
flag : Bool;
temp : Real;
value1 : Real;
data : "UDT_PropulsionCommand";

Was selbsterklärend bedeutet

Ein guter Variablenname sagt, was der Wert im Prozess bedeutet: Anforderung, Feedback, Befehl, Zustand, Grenzwert, Freigabe, Fehler oder Konfiguration. Er soll nicht nur sagen, dass ein Wert existiert.

Kontextreiche Namen für Analogskalierung

VAR_INPUT
    inRawAnalogValue : Int;
    rePhysicalMinimum : Real;
    rePhysicalMaximum : Real;
END_VAR

VAR_OUTPUT
    reScaledPhysicalValue : Real;
    xboSignalFaultActive : Bool;
END_VAR

VAR_TEMP
    _reNormalizedInput : Real;
END_VAR

Diese Namen machen die Skalierungsabsicht klar: Rohwert des Sensors hinein, physikalischer Engineering-Wert hinaus, Fault-Flag als Status.

Präfixe für Variablen¶

Verwende kurze Typpräfixe konsistent.

Präfix	Typ / Zweck	Beispiel
`xbo`	Boolean	`xboWireBreakDetected`
`in`	`Int`	`inRawAnalogValue`
`re`	`Real`	`reScaledTemperatureDegC`
`di`	`DInt`	`diEncoderCount`
`by`	`Byte`	`byAlarmPriority`
`wo`	`Word`	`woTelegramStatus`
`dw`	`DWord`	`dwDiagnosticMask`
`tim`	`Time`	`timAlarmDelay`
`dtl`	`DTL`	`dtlEventTimestamp`
`st`	Struct- oder UDT-Instanz	`stDriveStatus`
`arr`	Array	`arrGeneratorStatus`
`e`	Enumerationsähnlicher Wert	`eSystemMode`
`_`	Interner Static-/Temp-Helfer	`_reFilteredValue`

Interne Hilfsnamen

Präfixiere interne statische oder temporäre Hilfsvariablen mit _, wenn sie nicht mit der öffentlichen Schnittstelle verwechselt werden sollen. Beispiel: _reNormalizedInput.

Boolean-Namen¶

Boolean-Namen sollen sich wie True/False-Aussagen lesen.

GutVermeiden

xboPowerLimitActive
xboWireBreakDetected
xboStationHasControl
xboDriveReadyForCommand

xboPowerLimit
xboWire
xboStation
xboReady

Mehrdeutige Booleans erzeugen Fehler

Schwache Namen zwingen die Leserin oder den Leser zu fragen, ob der Wert eine Anforderung, ein Zustand, eine Freigabe, ein Fehler oder eine Konfiguration ist.

Einheiten¶

Setze die Engineering-Einheit in den Variablennamen, wenn die Einheit relevant ist.

GutVermeiden

reRequestedSpeedRpm
reAvailablePowerKw
reBusVoltageV
reTemperatureDegC
timStartDelay

reRequestedSpeed
reAvailablePower
reVoltage
reTemperature

Info

Einheitensuffixe verhindern Fehler, wenn Werte zwischen HMI, PLC-Logik, Antriebstelegrammen und Simulation bewegt werden.

Klarheit der Schnittstelle¶

Verwende klare Schnittstellenabschnitte und halte Inputs, Outputs und In/Out-Variablen fokussiert.

GutVermeiden

VAR_INPUT
    xboEnable : Bool;
    reRequestedPowerKw : Real;
    reAvailablePowerKw : Real;
END_VAR

VAR_OUTPUT
    reLimitedPowerCommandKw : Real;
    xboPowerLimitActive : Bool;
END_VAR

VAR_INPUT
    enable : Bool;
    in1 : Real;
    in2 : Real;
END_VAR

Kommentare¶

Kommentare sollen erklären, warum der Code existiert, nicht wiederholen, was der Code bereits sagt.

GutVermeiden

// Keep the previous valid value during wire break to avoid a step change at the drive command.
reScaledPhysicalValue := _reLastValidValue;

// Assign value.
reScaledPhysicalValue := _reLastValidValue;

Verwende Kommentare für Annahmen, Grenzen, Diagnosen und nicht offensichtliche Entscheidungen.

Praktische Checkliste¶

Vor dem Hinzufügen oder Deployen eines Bausteins

Das Bausteinpräfix passt zum Objekttyp.
Die Datei liegt im richtigen Subsystemordner.
FB-, FC- und OB-Header sind vorhanden und aktuell.
DB- und UDT-Sources folgen dem generierten TIA-STRUCT-Stil ohne Kommentare.
Variablennamen beschreiben Engineering-Bedeutung und Einheiten.
Boolean-Namen lesen sich wie True/False-Aussagen.
Größere Bausteine verwenden nummerierte REGION-Abschnitte.
Temporäre Hilfsnamen dringen nicht in die öffentliche Schnittstelle.