Get Better at Writing Comments

Some developers don’t like to document their code. And when they have to do it, they often miss the point.

By “document” here, I mean the code documentation, i.e. everything which is written in the code to explain how the code is supposed to work (inline comments, Javadoc, etc.).

All the developers are used to this kind of documentation, at least as readers, because it’s this documentation which will help them to understand the code of a co-worker, or how to use an external library. Yet, most of them don’t know how to write good comments and a good documentation.

Here’s a typical example of what I mean:

At first sight, we could say this code is documented. It has:

• A Javadoc comment for the public function computeValues(int x)
• Several comments in the body of the function

While this is the strict minimum (a Javadoc comment for the class should be present), the documentation here is pretty useless. We will see why and how you can improve your comments so your co-workers won’t try…