Writing effective code comments

Good Programming Practices

- Writing effective code comments

First we need understand who will read my comments and why we write comments.

Who will read the comments?
This can make us know what we need write in the comments.
For developers who maintain our code, including ourselves.
For developers who will be interested in our project, want to use our project, call the exposed API.
One thing to remember is that they might be reading only the generated documentation without access to the source code.

Why we write comments?
There are already many arguments why we need comment, here I only want to say why we want to take time and efforts to write comment, and what we can benefit from it?

For our own sake, writing comments is a good habit that forces us to think and record why we write the code in this way.
It is also a good habit that forces us to plan and proof-read our own work.
Comments should be written before the code itself.
This can help us to understand what this class/method does, and whether/why it is needed.
This can force us to think deeper and improve our solution before really write code. A poorly conceived function will become more apparent when we try to explain our thinking in the comments.
This can also help use to save our time and effort.
If we write code in a hurry and later find it doesn't work or doesn't work as we wish, then we will have to rewrite it. It is always harder to find bugs and rewrite it and make sure our change doesn’t affect other component.

Comment is especially important for a project's successful, especially for an open source project.
If we want more users/developers use our project, extend it, or help us to maintain it, provide patch for it, good and complete documentation is essential.

Nobody would like to use the project if they have to strive hard to understand how to call the API, how to use it. Nobody would help us to maintain it, if he can't quickly understand the project source code.

How to write effective comments?
The most effective way is to choose more meaningful method/class name, which can explain itself.

Explain what a function does, not how it is implemented.
Explain why the function exists.
Document all checked and unchecked exception.

l          Document precisely the conditions under which each one is thrown using the Javadoc @throws tag.

Document parameter conditions, such as whether it can be null etc.
Document Requirements (pre-conditions)

l          What inputs do we need, and what state must the object be in, for this method to work?

Document Promises (post-conditions)

l          What state is the object in, and what values are returned, on successful completion of this method?

Document the invariants

l          Invariants are used to check that some condition holds during the execution of this method.

Document thread-safety.
Why this method is synchronized, and why not?
What this element can do, and what can't.
What should a user avoid doing with the API element?
How does this differ from any similarly named API elements?


Rules for Effective API Documentation
Document all API elements
Avoid un-documentation - say more than just the obvious
Don't postpone.
It's best to write comments first before delving into code, and never check-in undocumented code.
Write to the reader, not yourself.
Be concise
Use code examples when appropriate
Use cross-linking extensively
Be professional
Write complete and grammatically correct sentences that end with a period.
Use correct spelling and capitalization.

Resources:
Writing Code Comments for Effective API Reference Documentation
Writing effective code comments