Week In Review : Code Comment
This week I decided to bring up the topic of code comment. A lot of developer do not use readable code or code comment. They tend to think that the application is going to be a one shot. Do and forget. In reality, that is not what happens. Code maintenance is an ongoing process.
In Why Write Code Comment, we cover the reason for writing code comment. The most important thing is that code comment must reflect WHY the code is written in a certain way.
In How To Write Good Code Comment, we cover best practices to write code comment. There are seven best practices:
1. Write readable code.
It makes a lot more sense to write self commenting code.
2. Write why, not how
Explain why the code is written a certain way. All developers know how to write the code.
3. Write assumption
This is very useful when you are writing a function or API. So, the input parameter is known.
4. Write reported bugs number.
If the code is a bug fix and there is a bug report system, it is best to write the bug report number in the comment.
5. Write briefly
No one likes to read long comment
6. Write comment when committing to repository
It is evil to use code repository such as subversion or git and write nothing on comment section when committing.
7. Write coding standard and information at the top
Always write coding standards and important information at the top of the file.
In When To Write Code Comment, we cover the best time to write code comment. It should always be written immediately, while our memory of the logic and reason are still fresh.
In Where Do We Write Code Comment, we cover the best location to write code comment. It should be written before the code begins. Coding conventions and standards must always be written at the top of the file.
Got any tips for code comment ? Do share with us in the comment section below.