Three rules for good programming
Recently, I have seen a little really good code, a lot of mediocre and a lot of bad one. (A lot of what I wrote before - especially when I was just starting out - refers to the latter, alas.) Reading random articles on the Internet and professional books, I came to the conclusion that writing good code is easy. Incredibly difficult, but at the same time easy. In fact, it is so simple that it comes down to three rules.
Observing them constantly, you will write good code. In any programming language and in any paradigm. The problem is that it is very difficult. All of them require discipline, and for the latter two, in most cases, long reflections are also needed.
This is the most important of the three rules that underlies the other two. Write a code that is simple for a person; leave the hard work to the computer. Use meaningful variable and method names. Do not create confusing logical chains where simple ones can be applied. Do not try to fit as much as possible on one line. Follow a consistent coding style with meaningful indentation. If your files are so bulky that it becomes difficult to scroll through them, break them into several small ones.
Many programmers try to write something that in their opinion works faster, reduces the size of the application - in a word, it “facilitates” the work of the computer. This is great, but don't forget that it’s much more important to write code that is easy to read and maintain for other people.
Your compiler (or interpreter) can handle completely different styles of code. For him, n and numberOfObjects are the same thing. For people, no. They will be read for a long time in the code, even if the purpose of the variable seems obvious to you.
Imagine that you made a small script for yourself, and after a few years you needed to change it a little. What would you rather see: a well-structured script with comments and an understandable name, or one function without a single comment and with variables whose purpose is almost impossible to understand?
If you are doing something unobvious to optimize part of the code, describe in the comment what exactly it does. But do not forget that in most cases you will not be able to optimize the program better than the compiler. The reality is that he is smarter than you. This is a fact: compilers have improved over decades of hard work by professionals. There are exceptions, but they only confirm the rule.
Write code that people can understand.
I can’t count how many times the same piece of code I met in different parts of the program. Just today, I was working on a large function in legacy code and saw the same conditions in two different parts of a conditional expression. I had to spend time trying to make sure that this was just a programmer's mistake.
When you repeat the same fragment in several places, sooner or later you will have to come back to it to correct some mistake or add something new. This makes code maintenance difficult. Instead of repeating yourself, put the fragment in a separate class or function that you can access as soon as you need it. If you call several methods in different places in the same order, wrap it in a separate function.
Think about what will be easier to understand when getting acquainted with the code: a 30-line fragment to free a block of memory, or a call to the clearMapVariableMemory () function ?
You may need to study the fragment later, but even then, working with a separate function will be easier.
The same principle can be applied to data. If you often use the same variables, transfer them to a separate class or data type.
If you follow this rule, all changes will be universal - you do not have to process dozens of places to make a small amendment.
Do not repeat yourself.
The last rule is based on the two previous ones: each piece of your code should perform only one task. It is true at all levels: for expressions, functions and methods, classes and objects.
A few years ago, one developer showed me a broken piece of code. In order to understand it, the programmer took several hours. As a result, the problem was discovered in the post-incremental C statements (in special cases, their behavior varies from compiler to compiler). Subsequently, reading one development book, I noted that the real problem was not with the operators, but with the fact that one fragment was responsible for many different tasks.
As far as I remember, the line containing the error was part of the ternary operation. That, in turn, performed several operations on pointers to calculate the condition, and several more, depending on the result of the conditional expression. This was a good example of writing code primarily for a machine, and not for a person: no one except the author of the fragment will understand what the line does, even after reading it several times. If the programmer who wrote the code broke the logic into several parts, it would have taken much less time to solve the problem.
You should not extract, process and modify data in the same method. A verbal description of each function should be placed in one sentence. The purpose of each line should be clear. This makes the code understandable to people. None of us can store in our head a function several thousand lines long. There is no substantial reason to create such functions instead of several small methods used together.
It should be noted that this is not so difficult: to complete one large task, you just need to break it into several smaller ones, each of which is in a separate function. It is important to ensure that the purpose of each function remains clear, otherwise the code becomes too confusing.
Each piece of your code should perform one task.
Writing good code is hard work. I have been programming for four years - not so long, but enough to see quite a few problems, including mine. It became clear to me that we complicate the development without following these simple rules. It is difficult to observe them correctly: it is not always obvious where a separate class or method is needed. This is a skill. It takes a long time to become a good programmer. But if we do not follow these rules, writing and maintaining the code will become even more difficult.
Translation of the article Good Programming in 3 Simple Rules .
- Write code for people, not cars.
- Do not repeat yourself.
- Each piece of code should perform one task.
Observing them constantly, you will write good code. In any programming language and in any paradigm. The problem is that it is very difficult. All of them require discipline, and for the latter two, in most cases, long reflections are also needed.
Write code for people, not cars
This is the most important of the three rules that underlies the other two. Write a code that is simple for a person; leave the hard work to the computer. Use meaningful variable and method names. Do not create confusing logical chains where simple ones can be applied. Do not try to fit as much as possible on one line. Follow a consistent coding style with meaningful indentation. If your files are so bulky that it becomes difficult to scroll through them, break them into several small ones.
Many programmers try to write something that in their opinion works faster, reduces the size of the application - in a word, it “facilitates” the work of the computer. This is great, but don't forget that it’s much more important to write code that is easy to read and maintain for other people.
Your compiler (or interpreter) can handle completely different styles of code. For him, n and numberOfObjects are the same thing. For people, no. They will be read for a long time in the code, even if the purpose of the variable seems obvious to you.
Imagine that you made a small script for yourself, and after a few years you needed to change it a little. What would you rather see: a well-structured script with comments and an understandable name, or one function without a single comment and with variables whose purpose is almost impossible to understand?
If you are doing something unobvious to optimize part of the code, describe in the comment what exactly it does. But do not forget that in most cases you will not be able to optimize the program better than the compiler. The reality is that he is smarter than you. This is a fact: compilers have improved over decades of hard work by professionals. There are exceptions, but they only confirm the rule.
Write code that people can understand.
Do not repeat yourself
I can’t count how many times the same piece of code I met in different parts of the program. Just today, I was working on a large function in legacy code and saw the same conditions in two different parts of a conditional expression. I had to spend time trying to make sure that this was just a programmer's mistake.
When you repeat the same fragment in several places, sooner or later you will have to come back to it to correct some mistake or add something new. This makes code maintenance difficult. Instead of repeating yourself, put the fragment in a separate class or function that you can access as soon as you need it. If you call several methods in different places in the same order, wrap it in a separate function.
Think about what will be easier to understand when getting acquainted with the code: a 30-line fragment to free a block of memory, or a call to the clearMapVariableMemory () function ?
You may need to study the fragment later, but even then, working with a separate function will be easier.
The same principle can be applied to data. If you often use the same variables, transfer them to a separate class or data type.
If you follow this rule, all changes will be universal - you do not have to process dozens of places to make a small amendment.
Do not repeat yourself.
Each piece of code must perform one task.
The last rule is based on the two previous ones: each piece of your code should perform only one task. It is true at all levels: for expressions, functions and methods, classes and objects.
A few years ago, one developer showed me a broken piece of code. In order to understand it, the programmer took several hours. As a result, the problem was discovered in the post-incremental C statements (in special cases, their behavior varies from compiler to compiler). Subsequently, reading one development book, I noted that the real problem was not with the operators, but with the fact that one fragment was responsible for many different tasks.
As far as I remember, the line containing the error was part of the ternary operation. That, in turn, performed several operations on pointers to calculate the condition, and several more, depending on the result of the conditional expression. This was a good example of writing code primarily for a machine, and not for a person: no one except the author of the fragment will understand what the line does, even after reading it several times. If the programmer who wrote the code broke the logic into several parts, it would have taken much less time to solve the problem.
You should not extract, process and modify data in the same method. A verbal description of each function should be placed in one sentence. The purpose of each line should be clear. This makes the code understandable to people. None of us can store in our head a function several thousand lines long. There is no substantial reason to create such functions instead of several small methods used together.
It should be noted that this is not so difficult: to complete one large task, you just need to break it into several smaller ones, each of which is in a separate function. It is important to ensure that the purpose of each function remains clear, otherwise the code becomes too confusing.
Each piece of your code should perform one task.
Conclusion
Writing good code is hard work. I have been programming for four years - not so long, but enough to see quite a few problems, including mine. It became clear to me that we complicate the development without following these simple rules. It is difficult to observe them correctly: it is not always obvious where a separate class or method is needed. This is a skill. It takes a long time to become a good programmer. But if we do not follow these rules, writing and maintaining the code will become even more difficult.
Translation of the article Good Programming in 3 Simple Rules .