How To Write Good Code Comment

image

The function of code comment is to help developer understand the code better.

Code comment can help or hinder understanding of the reason behind the code.

Excessive commenting makes it difficult to read the actual code. In this case, code comment hinder code understanding.

So, how do we write good code comment ?

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.

A few good reads from the internet :

Got any good code comment practices ? Share with us in the comment section below.