An ST style guide: naming, comments, constants and version control

Who reads your code

Not the compiler. It is another engineer at 3 a.m. with the line down, and it may be you in two years. Everything in this lesson serves that moment.

Naming: a prefix that states the type

The convention usually called PLCopen style puts a short prefix on the name:

Which convention you pick matters far less than picking one for the whole project and writing it on one page.

The naming that matters more: tags from the drawing

In a real plant the names are not yours, they come from the P&ID. The level on tank 101 is LT-101 on the drawing, on the cable label and on the HMI, so in the code it is LT_101 or LT101_PV. The usual ISA-5.1 pattern is a first letter for the measured variable and following letters for the function:

The payoff is immediate: the technician reads the alarm on the screen, finds the same tag in the field, and opens the same name in the code. No translation, no guessing.

Comments: say why, not what

A comment that repeats the code is a liability you now have to maintain twice:

(* Bad: sets the pump to TRUE *)
Pump := TRUE;

(* Good: the vendor requires 30 s between starts to protect
   the starter coil. Reference: P-101 manual page 14 *)
tRestartDelay := T#30s;

Comment the reason for a number, the document it came from, the decision that looks odd, and the failure that made you write the line. Never comment what the code already says.

Keep a POU short

If you have to scroll to see where an IF started, it is too long. Practical markers:

• A POU fits in one or two screens.
• One clear job per POU: FB_Motor runs a motor; it does not also build reports.
• Repeated logic becomes a function block you instantiate, not a copy-paste.
• Decisions live in one place: do not set Pump in three different spots.

No magic numbers

An 85.0 in the middle of the code tells nobody anything, and changing it means searching the whole project:

VAR CONSTANT
  LEVEL_FILL_SP   : REAL := 85.0;   (* % fill stop *)
  LEVEL_HI_ALARM  : REAL := 90.0;   (* % high level alarm *)
  FILL_TIMEOUT    : TIME := T#60s;  (* max fill time before fault *)
END_VAR

IF rLevelF >= LEVEL_FILL_SP THEN
  iStep := 2;
END_IF

Anything the operator should change at runtime becomes a setpoint in a RETAIN variable edited from the HMI. Anything that never changes becomes a CONSTANT. A number buried in an expression is neither.

Version control for PLC code

Station_v3_final_FINAL.zip has caused real incidents. What works:

• A Git repository for the project, with ST exported as text files you can diff. Siemens, CODESYS and TwinCAT all export and import POUs as text.
• Commit messages that say why: "raise fill timeout to 90 s after the smaller pump was fitted".
• A tag for every version actually downloaded to a controller, with the date and the site. That is what an incident investigation will ask for.
• A backup of the whole project, not just the text: hardware, network and module configuration.
• A printed change log in the panel: who downloaded what, and when.

A word on OOP in IEC 61131-3

The third edition added METHOD, PROPERTY, INTERFACE, EXTENDS and IMPLEMENTS to the function block. CODESYS and TwinCAT support them well; other platforms partly or not at all.

When does it earn its place?

• It earns it when you are building a library for twenty similar machines: FB_ValveBase with FB_ValveDigital and FB_ValveAnalog extending it, and an I_Device interface offering Start, Stop and GetState so the station logic is written once.
• It does not on a station with two pumps and a valve. The abstraction costs more reading time than it saves, and the maintenance technician will not follow it.

And the rule that does not bend: if the code is handed to a maintenance team that does not think in objects, you are writing a future problem rather than an engineering solution. Clarity beats elegance every time.