Write and accept only readable code!
Article#: 00055
Date: 2021-03-04
Author: Radim
When writing a program, you need to make sure that it is written correctly so that it works...
However, the program must also be written so that it can be read by other team members or by someone who has to change the program "in a year".
When a program has a problem or a bug, it is easier to determine the cause of the problem when the program is written clearly and legibly.
In general, we spend more time reading a program than writing it.
Writing understandable code makes it easier for anyone to go through and revise the code.
The code should be written in such a way that all programmers can understand it.
Well-written source code is in itself the most detailed documentation of a program.
Everything the program really does is described here exactly.
You then just need to document what each function and module is doing, as the way how they do it can be found in the source code.
It is necessary to write the code so that it can be used and maintained for decades.
You never know if that won't really happen in the end.
Repeated use of the code and sharing among developers can greatly increase the productivity of the team.
Nobody will include unreadable code in their module.
On the contrary, readable and clear code will please everyone, because it saves work and you can learn something from the code.
It is important to write the code legibly right from the start.
Don't think that when everything is done, you have the time and desire to rewrite the illegible code more readable.
The person who takes over the program should assess the quality of the source code and complain the illegible code as defect and demand correction.
Readable code increases the speed of development and the quality of the created application.
© Radim-Automation, 2020–2025. All rights reserved.
Sharing of this article is permitted with proper attribution (link to the original page).
Related previous articles:
- Who knows it?
- Appoint a representative!
- Write down your best practices and processes!
- Do you really want to start with this?
- Store email messages in the project folder!
- I can see what you can not see
- More than just start and stop
- Safety first!
- Do the right things and do them right!
- Don't make it worse!
- Write a project diary!
- Keep the answers to the question "Why"
- Everything is difficult until it becomes easy
- Introduce the terminology and standardize it!
- Realize every good idea ASAP!
- Don't disappoint your customer!
- Assign tasks efficiently!
- Communication skills are extremely important
- Don't replace employees in the middle of the project!
- Develop a sense of responsibility!
- Recruit and retain the best employees!
- Get the things done with a small, motivated team!
- Focus on target!
- 9 women can't make a baby in a month
- Sharpen your axe before you start felling!
- Understand - Agree - Be Identified - Believe
- Don't hide any problem!
- Check the result!
- Keep it simple!
- Don't leave a work package half-finished!
- Development is evolution
- Don't neglect and don't skip any step!
- Transparency and reliability
Related next articles:
- Use a usefull styleguide!
- Why do automation projects fail?
- Project leader
- Learn from your journey!
- Modular software architecture
- Abbreviations
- Machine modularization
- Knowledge gained from a completed project is priceless
- Variable names
- Choice of programming language
- Documentation issues
- Event logger as the very first function implemented in the program
- Diagnostic tools
- My boss was a hero
- Version control system
- Maintain order in the program code
- Code formatting
- Dream of a platform-independent PLC program
- Keep everything you need together
- An irreplaceable employee
- Hidden dangers during commissioning
- The false illusion of rapid progress
Comment#: 00001
Date: 2021-03-04
User: Radim
We can also understand the code like an investment. So we should make the code reusable.
Comment#: 00002
Date: 2021-03-04
User: Radim
If the code is uncommented and incomprehensible, any change is extremely difficult.
Improper code changes can cause a number of errors somewhere else and make the program unsustainable.
Even a well-written program can get to such a state over time if it has been "improved" and expanded many times.
Comment#: 00003
Date: 2021-07-01
User: Radim
If people of different nationalities work on the program, only one agreed language (no doubt that English is the best choice) may be used in the program for object names and program comments.
Even if a preliminary program is to be written, conventions must be followed.
It is always easier to copy some parts of the preliminary program into the final program if the conventions have always been followed.
Comment#: 00004
Date: 2021-07-19
User: Radim
If we can reuse code that has already been written, it will take less effort and time. But beware! If this code is bad (there is a bug in it or it is illegible), we also quickly distribute it to many applications by reusing it. This causes numerous problems, all of which are very tedious to fix.
Comment#: 00005
Date: 2021-09-10
User: Radim
"Programmers like to use tricks, they feel great, like they are solving a difficult puzzle. And they win the respect of their colleagues. However, they are mostly unaware of the dangers of tricks. Tricks are like an explosive in construction. Sometimes it is advisable to use it if you know how to use it, but it is a very dangerous tool that can do a lot of damage if handled improperly.
It is therefore always important to weigh up whether it really makes sense to use the trick.
It must also be taken into account that code readers do not understand the tricks and we therefore have to comment on them in great detail."
Translated from:
- Petr Paleta. Computer Press (2003). Co programátory ve škole neučí.
Comment#: 00006
Date: 2021-10-28
User: Radim
"Most often we make a program more complicated when we try to fix something by forcibly adding more code."
- https://bonsai-development.cz/clanek/jak-na-jednoduchy-kod
Comment#: 00007
Date: 2021-10-31
User: Radim
"Think about how to design your programs to make it easier for those who will maintain them after you."
- https://norvig.com/21-days.html
Comment#: 00008
Date: 2022-09-13
User: Radim
"Writing good software requires a willingness to keep working at a problem, making code more readable, more efficient, and less error-prone over time by responding to feedback and thinking deeply about problems (sometimes the best tool is a pencil and paper for writing down your thoughts). Don’t expect to get things completely right the first time!"
- https://towardsdatascience.com/notes-on-software-construction-from-code-complete-8d2a8a959c69
Comment#: 00009
Date: 2022-11-14
User: Radim
"Software analysis experts agree that code quality has a remarkable growth of attention and demand these days. They confirm that continuous development of a software system makes the source code significantly complicated after numerous updates. Therefore, the team has to analyse the code on a continual basis to keep the code base in a good maintainable state. This will prevent uncovered technical debts, system crashes and expensive fixes."
- https://stackify.com/software-testing-tips/
Comment#: 00010
Date: 2023-06-08
User: Radim
"Investments in good code quality and good architecture are sustainable investments. Over 80% of development work is maintenance work and changes to existing code. Prof. Niklaus Wirth once said that SW is not written for the compiler, but for people who have to maintain the code. If the question of "quick and dirty" arises, the bearability of the "technical debt" must also be taken into account, because at some point the debt becomes unbearable or so great that a "fresh start" becomes cheaper. In terms of insurance, this is referred to as a “total loss”. In the case of “quick and dirty solutions”, people often “muddle” in the same style over and over again. In addition to existing bad codes, other "spaghetti lines" are no longer noticeable, a free pass...
This is how a vicious circle begins, because with the growing "technical debt", the development speed also slows down - due to unreadable and bad code. This delays the completion of new features and the project has to live with explosively increasing opportunity costs."
Translated from:
- https://blog.noser.com/kennen-sie-ihre-technische-schuld-wir-unterstuetzen-sie-bei-der-rueckzahlung/
Comment#: 00012
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#: 00014
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#: 00015
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#: 00016
Date: 2024-03-25
User: Radim
Remove the "ballast" from the program!
Only include things in the program that are really needed. Unnecessary parts of the code in the program become obsolete, untested, raise unnecessary questions and are a source of ambiguity.
Sometimes it is a good idea to try more than one way in practice to find out which way is the best. However, once we have decided on a particular approach, it is important to consolidate our methods and remove the outdated ones. By removing "ballast" from the program, we eliminate potential sources of confusion and improve the overall quality of the code.
Comment#: 00017
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