Structured Text Property Naming

[Kalavrat]

Hi,
In our company (programming mainly Beckhoff PLCs) we are establishing internal coding guidelines for ST. Until now, the conventions were always project specific.

We don't use Hungarian notation & we are consistent with using PascalCase for internal variables of a FB.
Trouble arises when you wish to expose a particular variable via property as you cannot use the same name.
In the past we've used _ prefix in the internal variable, to make the property look pretty, but I feel that this makes internals of a FB harder to read.

Is there any established way to name the properties?

For example if I have an internal variable MotorPosition, I can expose it via property "MotorPositionProperty" (snippet below)

FUNCTION_BLOCK FunctionBlock
VAR
    SensorReadback : INT := 0; (* Internal variable)
    MotorPosition : INT := 0;  (* Internal variable *)
    DeviceState   : BOOL := FALSE;  (* Internal variable *)
END_VAR

PROPERTY MotorPosition[B]Property[/B] : INT
    GET : INT
        RETURN MotorPosition;
    END_GET
END_PROPERTY

Alternative is to prefix internal variable with _ and keep the property as MotorPosition.

FUNCTION_BLOCK FunctionBlock
VAR
    SensorReadback : INT := 0; (* Internal variable)
    [B]_motorPosition[/B] : INT := 0;  (* Internal variable *)
    DeviceState   : BOOL := FALSE;  (* Internal variable *)
END_VAR

PROPERTY MotorPosition : INT
    GET : INT
        RETURN _motorPosition;
    END_GET
END_PROPERTY

I feel like the second approach makes for less readable code while the first one adds additional clutter to the property name.
Any ideas on how to handle this elegantly?
How do you handle this in your coding?

 

[Zensequitur]

I personally like the second option with the prefixed underscore. But tend to otherwise avoid the use of snake_case and instead prefer, PascalCase. This more closely mirrors my work in C# where I started back in the day with the whole 'm_Internal' member variables, then moved to the prefix underscore later when the Microsoft did similar with their coding styles.

Beckhoff has posted their internal naming conventions, but this is really just Hungarian Prefix notation. It is how most if not all of their libraries are laid out, and how most code should be written when receiving sample code from an AE or other internal resource. I also tend to lean toward more Hungarian notation but typically only when developing library FB's and other types that may be shared externally, but I want to look more like the existing libraries from Beckhoff.

At the end of the day, coding practices are used to develop consistency, with the ultimate goal that code becomes more uniform and readable.

I recommend that you find the syntax and format style that is most easily digested by the majority of your team. Then be consistent, and enforce those rules. Perhaps even using the TE1200 Static Analysis engineering addon.
TE1200 TwinCAT 3 PLC Static Analysis



Patrick

 

[ojz0r]

Actually in Pascal the variables of a class/record (struct)/object is usually prefixed with an F (as in field).
So in your case the variable name would be FMotorPosition.


The method for getter/setter is prefixed with GetMotorPosition and SetMotorPosition (where applicable). In the setter method you could do some range checking and similar to prevent faulty values.

 

[theColonel26]

Hi,
In our company (programming mainly Beckhoff PLCs) we are establishing internal coding guidelines for ST. Until now, the conventions were always project specific.

We don't use Hungarian notation & we are consistent with using PascalCase for internal variables of a FB.
Trouble arises when you wish to expose a particular variable via property as you cannot use the same name.
In the past we've used _ prefix in the internal variable, to make the property look pretty, but I feel that this makes internals of a FB harder to read.

Is there any established way to name the properties?

For example if I have an internal variable MotorPosition, I can expose it via property "MotorPositionProperty" (snippet below)

FUNCTION_BLOCK FunctionBlock
VAR
    SensorReadback : INT := 0; (* Internal variable)
    MotorPosition : INT := 0;  (* Internal variable *)
    DeviceState   : BOOL := FALSE;  (* Internal variable *)
END_VAR

PROPERTY MotorPosition[B]Property[/B] : INT
    GET : INT
        RETURN MotorPosition;
    END_GET
END_PROPERTY

Alternative is to prefix internal variable with _ and keep the property as MotorPosition.

FUNCTION_BLOCK FunctionBlock
VAR
    SensorReadback : INT := 0; (* Internal variable)
    [B]_motorPosition[/B] : INT := 0;  (* Internal variable *)
    DeviceState   : BOOL := FALSE;  (* Internal variable *)
END_VAR

PROPERTY MotorPosition : INT
    GET : INT
        RETURN _motorPosition;
    END_GET
END_PROPERTY

I feel like the second approach makes for less readable code while the first one adds additional clutter to the property name.
Any ideas on how to handle this elegantly?
How do you handle this in your coding?

I am a codesys guy and haven't done anything with Beckoff, but since Bechoff still uses the Codesys Compiler, and I assume runtime tool kit to build their runtimes, it is all still applicable.

I use the C# style Guide Lines
https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/identifier-names
The only exception is with private/internal fields

if it is just an internal field and not a direct property backer. then I use camel case.

If it is a property backer then I use a _prefix and camel case. the only reason I do this is so that I can use a script to auto generate Properties on every field that is prefixed with an underscore.

FUNCTION_BLOCK FunctionBlock
VAR_Input
    CMD_Execute : BOOL;



END_VAR



 VAR
    sensorReadback : INT := 0; (* Internal field *)
    [B]_motorPosition[/B] : INT := 0;  (* Internal field: property backer *)
    deviceState   : BOOL := FALSE;  (* Internal field  *)
END_VAR

PROPERTY MotorPosition : INT
    GET : INT
        RETURN _motorPosition;
    END_GET
 END_PROPERTY

Side Note!!!!:

Beckhoff allows you to use the return keyword to return a value? In Codesys you have to use the Method/Function/Property Name and it is absolutely ridiculous and a pain.

Beckhoff has posted their internal naming conventions, but this is really just Hungarian Prefix notation. It is how most if not all of their libraries are laid out, and how most code should be written when receiving sample code from an AE or other internal resource. I also tend to lean toward more Hungarian notation but typically only when developing library FB's and other types that may be shared externally, but I want to look more like the existing libraries from Beckhoff.

At the end of the day, coding practices are used to develop consistency, with the ultimate goal that code becomes more uniform and readable.

I recommend that you find the syntax and format style that is most easily digested by the majority of your team. Then be consistent, and enforce those rules. Perhaps even using the TE1200 Static Analysis engineering addon.
TE1200 TwinCAT 3 PLC Static Analysis

Hungarian notation is very antiquated, it is from a time when IDEs were premative and it was a pain to figured out what time a variuable one. Now with modern IDEs you just hover over the variable and it will give you a tool tip with the type, also you can just Right CLick -> "Go to Definition" too.

Beckhoff inherited Hungarian notation from Codesys like 30 years ago. The reason it has last this long is because Codesys and Bechhoff are lazy and never rewrote there libraries with modern coding practices. Codesys has dropped Hungarian notation from brand new Libraries, and are also now using OOP, which they still technically say you shouldn't do in there Official Style Guide for libraries...

Actually in Pascal the variables of a class/record (struct)/object is usually prefixed with an F (as in field).
So in your case the variable name would be FMotorPosition.

That is yucky :angr:

maaaaaaaybe for internal fields, but external fields that makes me want to scream

The method for getter/setter is prefixed with GetMotorPosition and SetMotorPosition (where applicable). In the setter method you could do some range checking and similar to prevent faulty values.

TwinCATs and Codesys have Properties now so you don't need to do separate Get and Set Methods. They are both wrapped with the property.

 

[Zensequitur]

Hungarian notation is very antiquated, it is from a time when IDEs were premative and it was a pain to figured out what time a variuable one. Now with modern IDEs you just hover over the variable and it will give you a tool tip with the type, also you can just Right CLick -> "Go to Definition" too.

Beckhoff inherited Hungarian notation from Codesys like 30 years ago. The reason it has last this long is because Codesys and Bechhoff are lazy and never rewrote there libraries with modern coding practices. Codesys has dropped Hungarian notation from brand new Libraries, and are also now using OOP, which they still technically say you shouldn't do in there Official Style Guide for libraries...

I Agree 100% about Hungarian notation being antiquated. I Taught TC2 and TC3 classes as a Beckhoff Training Engineer, and in every class I covered this same thing when it came time to cover coding styles. I had the same explanation as you, Modern IDE's have mouse over tool-tips, use them, Right click, Go to Definition practice using it. I had a lot of legacy training materials and many, many old libraries that I had to teach from. So, I defaulted to following the Hungarian carpal tunnel system. Merely to be consistent with presentation materials and standard libraries. Beckhoff has ultimately started moving forward on some of their newer stuff, and embracing the more modern naming conventions, though, they are still really stuck on the whole Hungarian thing.

I always recommended the C# coding styles and conventions, as I learned C# from 1.1 days 20 years ago, and only learned PLC stuff and ST a few years later. TwinCAT only since 2015.



Patrick

 

[Kalavrat]

if it is just an internal field and not a direct property backer. then I use camel case.

If it is a property backer then I use a _prefix and camel case. the only reason I do this is so that I can use a script to auto generate Properties on every field that is prefixed with an underscore.

This resembles what we currently use on other projects. I might be alone in this, but I feel that this somewhat ruins the readability of FB's internals. (there's no reason for field & property backer to look different IMHO)

Beckhoff allows you to use the return keyword to return a value? In Codesys you have to use the Method/Function/Property Name and it is absolutely ridiculous and a pain.

Actually no. It's the same with Beckhoff. You'd return a value via MotorPosition:=_motorPosition;
But I thought it might confuse people, so i stuck with return for this example.



Further I have also thought about adding Get and Set prefixes to the properties.

GetMotorPosition
 (remove setter, so that only getter is available in this property)

However if a property has both (getter & setter) then you would have to split it in two properties;

GetMotorPosition
 (contains only getter)

SetMotorPosition 
 (contains only setter)

Any opinions? I need to give it a bit more thought still..