Commenting code
No matter what language we write the program, it is necessary to comment.
Very often, comments do not perform their task, but simply create a volume and what is written has to be disassembled without prompts, sometimes referring to additional program files, which affects the speed of development.
The topic itself decided to write after I had to improve some of my old programs. In particular, I faced the fact that when I wrote them I did not give proper attention to writing comments and as a result 4 years passed and I stepped on my rake, having spent too much time analyzing my old code. Therefore, this topic was born, in order to focus on the importance of comments in the code. Conclusions were made, which I share below.
Good comments allow you to work only with a specific piece of code and not to look for answers in other places, they answer those questions, the answer to which we cannot find in this place.
')
I decided to remind a few tips that you need to follow when writing comments to the code.
0. The priority task of each programmer is actual comments.
1. “Write the code as if it would be accompanied by a violent psychopath who knows where you live.” - McConnell, Steve .
2. Commenting on the code for yourself (correctly, so that others understand).
3. No need to comment on the obvious.
4. The comment should complement the code, and not rephrase it.
5. If the code uses standard functions, constructions or classes described in the language elements of the language, then do not waste your time, in this case only the correct code will help.
6. Comment to the code snippet, you need to write with the same indentation as that of the commented code.
7. The bad habit of many - to talk to someone in the commentary, the comment should be short and clear.
8. In the commentary, you can leave the task for later, which for some reason is not completed at the moment. I do not advise you to keep such notes in a separate file, because, besides you, someone else can work on the code and it is easier if it is in place to see where and what is not completed, but it will be implemented. Perhaps more relevant solutions will be found.
9. Good practice - at the beginning of the file briefly describe its purpose.
10. New classes and functions - it is desirable to describe what and from where the incoming data and what purpose.
11. In order to get rid of unnecessary code comments, you can choose the name of classes, functions, objects, etc. to destination.
As a result, we and our colleagues will not spend too much time commenting. We will not annoy people who will take to disassemble the code, and even please them at some point.
Also for fans of voluminous comments I can advise you to replace them with separate documentation.
Save your time and spare those who will work on your code.
PS Congratulations to all on the past holiday programmer, I wish that your interests and your work - were one. So that the customers were excellent and any started business was brought to success.
Very often, comments do not perform their task, but simply create a volume and what is written has to be disassembled without prompts, sometimes referring to additional program files, which affects the speed of development.
The topic itself decided to write after I had to improve some of my old programs. In particular, I faced the fact that when I wrote them I did not give proper attention to writing comments and as a result 4 years passed and I stepped on my rake, having spent too much time analyzing my old code. Therefore, this topic was born, in order to focus on the importance of comments in the code. Conclusions were made, which I share below.
Good comments allow you to work only with a specific piece of code and not to look for answers in other places, they answer those questions, the answer to which we cannot find in this place.
')
I decided to remind a few tips that you need to follow when writing comments to the code.
Some tips
0. The priority task of each programmer is actual comments.
1. “Write the code as if it would be accompanied by a violent psychopath who knows where you live.” - McConnell, Steve .
2. Commenting on the code for yourself (correctly, so that others understand).
3. No need to comment on the obvious.
4. The comment should complement the code, and not rephrase it.
5. If the code uses standard functions, constructions or classes described in the language elements of the language, then do not waste your time, in this case only the correct code will help.
6. Comment to the code snippet, you need to write with the same indentation as that of the commented code.
7. The bad habit of many - to talk to someone in the commentary, the comment should be short and clear.
8. In the commentary, you can leave the task for later, which for some reason is not completed at the moment. I do not advise you to keep such notes in a separate file, because, besides you, someone else can work on the code and it is easier if it is in place to see where and what is not completed, but it will be implemented. Perhaps more relevant solutions will be found.
9. Good practice - at the beginning of the file briefly describe its purpose.
10. New classes and functions - it is desirable to describe what and from where the incoming data and what purpose.
11. In order to get rid of unnecessary code comments, you can choose the name of classes, functions, objects, etc. to destination.
Conclusion
As a result, we and our colleagues will not spend too much time commenting. We will not annoy people who will take to disassemble the code, and even please them at some point.
Also for fans of voluminous comments I can advise you to replace them with separate documentation.
Save your time and spare those who will work on your code.
PS Congratulations to all on the past holiday programmer, I wish that your interests and your work - were one. So that the customers were excellent and any started business was brought to success.
Source: https://habr.com/ru/post/128229/
All Articles