Variable names
Article#: 00072
Date: 2021-11-06
Author: Radim
A variable is a storage location for data.
We should choose a name for the variable that best describes what the variable is used for and what data is stored in the variable.
The usefulness of correct variable names is often underestimated and insufficient attention and time is devoted to choosing appropriate variable names.
The name of any variable should be such that no comment or additional explanation is required.
It must be easy to read and sufficiently descriptive.
The clearer the variable names, the clearer the entire program.
What should be the optimal length of the variable name?
It must be determined whether the development environment limits the length of the names of variables and other objects in the program.
Whenever possible, it is better not to use any or very few abbreviations.
If we have to choose an abbreviation so that the variable name does not become too long, three letters seem appropriate (neither too many nor too little) to shorten the word in the variable name.
The optimal length of the variable name is chosen so that the name is meaningful enough and at the same time easy to read, ie not too long.
Lower case or upper case?
Pascal Case (also known as Upper Camel Case) – a word composition without spaces, where each word starts with a capital letter – is, in my opinion, a good choice for a balanced ratio of space saving and legibility.
If we want to separate one word more in the name of the variable, we can also use an underscore.
Should the variable name also contain the data type of the variable?
Not in my opinion.
There were probably reasons for embedding the data type in a variable name in the past, when the development environment did not inform the programmer about the variable type in the tooltip when moving mouse pointer over the variable.
Today, in my opinion, it no longer makes sense to write the data type in the variable name. It takes up unnecessary space, makes it difficult to read, and increases the workload when we decide to change the data type of a variable.
What else should the variable name contain?
It makes sense to use a prefix in the variable name to indicate whether it is a global, local, input or output variable (e.g. Glo_, Loc_, Inp_, Out_).
Actual value and its setpoint can have the same variable name in the program with the differentiation at the end of the variable name (e.g. _Acl for actual value and _Dsr for desired value).
If the variable contains a value of a quantity with a certain unit, it is advantageous to write the unit in the variable name in order to avoid doubts.
It often happens that in a program we convert a quantity from one unit to another, so we have two variables and each is determined by its name (e.g. Speed_Hz and Speed_RevPerMin).
How do we put the variable name together?
Words in the variable name should describe the variable from generally left to more precisely right.
In this way, the names of the variables become symmetrical - the beginning of the variable is the same for the variables that are related to each other and if they are ordered alphabetically one below the other in the declaration, it is easier to get an overview of which variables are used.
e.g.:
Loc_MotorSpeed_Acl_Hz
Loc_MotorSpeed_Acl_RevPerMin
Loc_MotorSpeed_Dsr_Hz
Loc_MotorTorque_Acl_Nm
© Radim-Automation, 2020–2025. All rights reserved.
Sharing of this article is permitted with proper attribution (link to the original page).
Related previous articles:
- Machine modularization
- Abbreviations
- Modular software architecture
- Think critically!
- Learn from your journey!
- Why do automation projects fail?
- Use a usefull styleguide!
- Write and accept only readable code!
- Appoint a representative!
- HMI and PLC applications should grow together
- Do you really want to start with this?
- I can see what you can not see
- More than just start and stop
- Do the right things and do them right!
- Everything is difficult until it becomes easy
- Introduce the terminology and standardize it!
- Realize every good idea ASAP!
- Stay alert!
- Don't disappoint your customer!
- Communication skills are extremely important
- Develop a sense of responsibility!
- Focus on target!
- Think on paper!
- Sharpen your axe before you start felling!
- Check the result!
- Keep it simple!
- Don't leave a work package half-finished!
- Success is not a matter of coincidence
- Development is evolution
- Don't neglect and don't skip any step!
- Transparency and reliability
- From an idea to a consistent system
Related next articles:
- Choice of programming language
- Event logger as the very first function implemented in the program
- Version control system
- Keep the documentation up to date throughout the project
- Maintain order in the program code
- Code formatting
- Dream of a platform-independent PLC program
- The false illusion of rapid progress
Comment#: 00001
Date: 2021-11-06
User: Radim
"You may not appreciate proper naming until you come to code that you need to understand and that has incorrectly named variables."
- https://bonsai-development.cz/clanek/ve-spravnem-pojmenovani-promennych-je-sila
Comment#: 00002
Date: 2021-11-06
User: Radim
"Even if you are only using a variable as a temporary value store, still give it a meaningful name."
- https://towardsdatascience.com/data-scientists-your-variable-names-are-awful-heres-how-to-fix-them-89053d2855be
Comment#: 00003
Date: 2021-11-06
User: Radim
"Your code will be read more times than it is written. Prioritize how easy your code is to understand rather than how quickly it is written."
- https://towardsdatascience.com/data-scientists-your-variable-names-are-awful-heres-how-to-fix-them-89053d2855be
Comment#: 00004
Date: 2021-11-06
User: Radim
"Overall, by trying to write code faster — using shorter variable names — you will actually increase the development time of your program!"
- https://towardsdatascience.com/data-scientists-your-variable-names-are-awful-heres-how-to-fix-them-89053d2855be
Comment#: 00005
Date: 2021-11-06
User: Radim
"Use descriptive loop indexes instead of i, j, k."
- https://towardsdatascience.com/data-scientists-your-variable-names-are-awful-heres-how-to-fix-them-89053d2855be
Comment#: 00006
Date: 2022-07-06
User: Radim
It makes sense to name the variables in such a way that when you search for the name of the variable in the program, only the variable you are looking for is returned. This can be achieved, for example, by using the leading wildcard '0' depending on the number of digits in the number. (E.g. if I search for 'Index1' I also get 'Index10' back. So it's better to name the variable 'Index01' if I know in advance that I will define more than 9 indexes to to avoid ambiguity.)
Comment#: 00007
Date: 2022-07-07
User: Radim
Also, name the variables consistently throughout the program so that it is easy to follow the 'thread' and find occurrences and uses of the variable in the program. This tip is especially important when a variable passes its value to another variable.
Comment#: 00008
Date: 2022-11-30
User: Radim
If we need to choose an abbreviation for the name of a variable or any other element in the program, it is advisable to choose such a combination of letters that will indicate its full meaning, and it is also advisable to choose such a combination of letters that when we do that Search the program for occurrences of this abbreviation, it returns nothing but all occurrences of this abbreviation. This means that the abbreviation should not appear in any word used in the program, so a global search for that abbreviation throughout the program is helpful.
Comment#: 00009
Date: 2023-04-11
User: Radim
IEC 61131-3: Coding Guidelines
- See more on: https://stefanhenneken.net/2016/04/08/iec-61131-3-coding-guidelines-2/#more-704
Comment#: 00010
Date: 2023-09-27
User: Radim
"By continuously improving the design of code, we make it easier and easier to work with.
This is in sharp contrast to what typically happens: little refactoring and a great deal of attention paid to expediently add new features.
If you get into the hygienic habit of refactoring continuously, you'll find that it is easier to extend and maintain code."
- Joshua Kerievsky. Addison-Wesley (2004). Refactoring to Patterns.
Comment#: 00011
Date: 2024-02-22
User: Radim
Is your native language not English and do you work in an international team? Have you agreed on English as the project language within the team? Then please:
1. Install and use all project tools in English.
2. Use English help files for the tools.
3. Write English variable names and comments in the code.
These rules make collaboration between team members, documentation and support tasks easier. Because people will use the same terms.
Do you agree with these rules?
Would you add anything else?
Comment#: 00012
Date: 2024-03-25
User: Radim
There are some advantages of alphabetically sorting variables within a declaration block:
1. Easier searching: When variables are sorted alphabetically, it is easier to find a specific variable because you know it will be located at a certain place in alphabetical order.
2. Faster updates and modifications: When updating or modifying existing variables, it is easier to find the relevant variable if variables are sorted alphabetically.
3. Simpler creation of new variables: When creating new variables, you can more easily choose a suitable name if you have an overview of all existing variables and their alphabetical order.
4. Code clarity and maintenance: Alphabetically sorting variables contributes to the clarity of the code and facilitates its maintenance because the programmer knows where to look for a specific variable.
However, it is important to adhere to consistent rules for naming variables.
Comment#: 00013
Date: 2024-04-10
User: Radim
"Code conventions are important to programmers for a number of reasons:
• 40%–80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
• If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create."
- https://en.wikipedia.org/wiki/Coding_conventions