September 13, 2011 at 13:16Code Commenting
It doesn’t matter what language we write the program in, it needs to be commented on.
Very often, comments do not fulfill their task, but simply create 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 several of my old programs. In particular, I was faced with the fact that when I wrote them I did not give due attention to writing comments and as a result 4 years passed and I stepped on my rake, having spent extra time analyzing my old code. Therefore, this topic was born in order to focus on the importance of comments in the code. The conclusions were drawn, which I share below.
Good comments allow you to work only with a specific piece of code and not look for answers in other places, they answer those questions, the answer to which we can not find in this place.
I decided to remind you of some tips that you need to adhere to when writing comments on the code.
0. The priority task of each programmer is relevant comments.
1. “Write the code as if it would be accompanied by a violent psychopath who knows where you live” - McConnell, Steve .
2. We comment on the code just for ourselves (competently, so that others understand).
3. No need to comment on obvious things.
4. The comment should supplement the code, and not rephrase it.
5. If the code uses standard functions, constructions or classes described in the basics of the language, then do not waste your time, in this case only correctly formatted code will help.
6.Commenting on the code fragment, you need to write with the same indentation as the commented code.
7. It is a bad habit of many to talk with someone in a comment, the comment should be short and clear.
8. In the commentary, you can leave the task for later, which for some reason has not been completed at the moment. I do not recommend storing such notes in a separate file, because, besides you, someone else can work on the code if it is in place to see where and what has not been completed, but 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 advisable to describe what and from where the incoming data gets and what purpose.
eleven.In order to get rid of unnecessary code comments, you can choose the name of classes, functions, objects, etc. by appointment.
As a result, we and our colleagues will not spend extra time commenting. We will not annoy people who will take to disassemble the code, and even delight them at some point.
Also, for lovers of voluminous comments, I can advise replacing them with separate documentation.
Save your time and spare those who will work on your code.
PS I congratulate everyone on the past holiday of the programmer, I wish that your interests and your work are one. So that the clients were excellent and any business started was brought to success.
Very often, comments do not fulfill their task, but simply create 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 several of my old programs. In particular, I was faced with the fact that when I wrote them I did not give due attention to writing comments and as a result 4 years passed and I stepped on my rake, having spent extra time analyzing my old code. Therefore, this topic was born in order to focus on the importance of comments in the code. The conclusions were drawn, which I share below.
Good comments allow you to work only with a specific piece of code and not look for answers in other places, they answer those questions, the answer to which we can not find in this place.
I decided to remind you of some tips that you need to adhere to when writing comments on the code.
Some tips
0. The priority task of each programmer is relevant comments.
1. “Write the code as if it would be accompanied by a violent psychopath who knows where you live” - McConnell, Steve .
2. We comment on the code just for ourselves (competently, so that others understand).
3. No need to comment on obvious things.
4. The comment should supplement the code, and not rephrase it.
5. If the code uses standard functions, constructions or classes described in the basics of the language, then do not waste your time, in this case only correctly formatted code will help.
6.Commenting on the code fragment, you need to write with the same indentation as the commented code.
7. It is a bad habit of many to talk with someone in a comment, the comment should be short and clear.
8. In the commentary, you can leave the task for later, which for some reason has not been completed at the moment. I do not recommend storing such notes in a separate file, because, besides you, someone else can work on the code if it is in place to see where and what has not been completed, but 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 advisable to describe what and from where the incoming data gets and what purpose.
eleven.In order to get rid of unnecessary code comments, you can choose the name of classes, functions, objects, etc. by appointment.
Conclusion
As a result, we and our colleagues will not spend extra time commenting. We will not annoy people who will take to disassemble the code, and even delight them at some point.
Also, for lovers of voluminous comments, I can advise replacing them with separate documentation.
Save your time and spare those who will work on your code.
PS I congratulate everyone on the past holiday of the programmer, I wish that your interests and your work are one. So that the clients were excellent and any business started was brought to success.