Name a few things that software developers always have strong opinions about and naming conventions on code is one of the things that surely will come up. What lengths for identifiers should we use? Should we use hungarian notation? CamelCase or under_score case? While programming guidelines covering these topics have been existing since the rise of the early programming languages, they are much less common for industrial control.
Initially the only one that I found was Beckhoff’s for TwinCAT 3. Most of Beckhoff’s libraries and example code used this, even though even Beckhoff themselves have not been consistent. More recently PLCopen have released their coding guidelines written specifically for IEC61131-3. Just out of curiosity I decided to compare the two standards and their take on naming conventions, and comparing them to my own personal opinions.
A quote that I often come to think of when you having many (and often colliding) standards is:
The nice thing about standards is that you have so many to choose from – Andrew S. Tanenbaum
The PLCopen guidelines mandate that any scheme can be used for prefixes, as long as the notation is documented. Beckhoff however have created rules for the name prefixes, which makes sense since they want to have common names for their own libraries. While PLCopen leaves it open to the developer to decide for the naming conventions, they have provided some examples of naming prefixes of different types, which in turn is a reference to the 3rd edition of IEC61131-3. If we look at the case for prefixes of variables they are:
| Type | Beckhoff | PLCopen |
|---|---|---|
| ENUM | e | e |
| ARRAY | a | a |
| STRUCT | st | |
| REFERENCE | ref ** | ref |
| FUNCTION BLOCK | fb | fb |
| PROGRAM | prg | |
| BOOL | b | x |
| SINT | n | si |
| INT | n | i |
| DINT | n | di |
| LINT | n | li |
| USINT | n | usi |
| UINT | n | ui |
| UDINT | n | udi |
| ULINT | n | uli |
| REAL | f | r |
| LREAL | f | lr |
| TIME | t | tim |
| LTIME | t | ltim |
| DATE | d | dt |
| LDATE | d | ldt |
| TIME_OF_DAY | td | tod |
| LTIME_OF_DAY | td | ltod |
| DATE_AND_TIME | DT | dt |
| LDATE_AND_TIME | DT | ldt |
| STRING | s | str |
| WSTRING | ws | wstr |
| CHAR | N/A | c |
| WCHAR | N/A | wc |
| BYTE | n | by |
| WORD | n | w |
| DWORD | n | d |
| LWORD | n | lw |
** only if not used as method input, in which case it shall be prefixed according to the basic data type of the reference
PLCopen also show examples for prefix of scope:
| Scope | Prefix |
|---|---|
| Global scope | g |
| Local scope | l |
| POU Parameter | p |
| Temporary variable | tmp |
And of control:
| Control | Prefix |
|---|---|
| Input | i |
| Output | o |
However, PLCopen mentions:
Attributes can be omitted if the Programming Support Environment clearly shows them by other means, for instance by hovering over it.
Which is my personal opinion, as the TwinCAT XAE (Visual Studio IDE) clearly shows the type of a variable by just hovering over it.
Hovering a variable “DonePrintingTestResults” in Visual Studio
In the screenshot we do not only clearly see the type (BOOL) but also the complete instance search path, what type of variable it is (instance, input, output) and the accompanying comment to the variable. This is a much clearer than for example putting “lin” in front of all integer and bit-based local input variable numbers, which is why I’ve started to avoid using prefixes altogether.
Regarding the use of case (capitals) then again PLCopen doesn’t mandate any particular standard other than that the use of capital letters in object names should be clear and consistent across the project. They do as a guideline however propose that:
- UPPER_SNAKE_CASE should be used for constants, user defined types and keywords
- Use UpperCamelCase for all other multi-word items
The Beckhoff rules doesn’t specify that that constants should be UPPER_CASE, but are on the same track with CamelCasing, let me quote:
If an identifier is made up of several words, the first letter of each word is capitalized (CamelCase). Usually, no delimiters such as ‘_’ are used between the words.
Personally I was all in for UpperCamelCase, but have started to doubt this since I decided to not let my opinions and feelings decide what I prefer, but rather let science speak. Considering the amount of developers around the world, someone must have done some science on this? I found this paper that in the abstract concludes:
Results indicate that camel casing leads to higher accuracy among all subjects regardless of training, and those trained in camel casing are able to recognize identifiers in the camel case style faster than identifiers in the underscore style.
“All fine then” I thought, but then I found a blog post that in the discussion puts forward some convincing arguments of why the results of the paper are flawed. At least the nerd inside of me got some fun reading on this topic.
At the end of the day, what matters are not the actual rules but rather that there are rules in a project and that they are used consistently followed. I would highly recommend you to read the PLCopen coding guidelines as they provide a good deal of information not only on naming conventions but more importantly on coding practices.
What are you personal preferences? Do you follow the Beckhoff or PLCopen naming conventions or do you have your own?