How to Properly Comment Code? (Part I)

If you do a search in Google for "code comment" you'll find 216,000 hits and if you do the search for "comment code" you'll find 505,000 hits. Then, why is so difficult to find properly commented code?

The first point that I want to clarify is that I'm talking about "commenting code" not "documenting code" which is slightly different.

The code documentation is used to generate the API documentation, to known which methods are available, what arguments are accepted and what's the result of the call. The documentation is destined to be used and understood by the users of your code (like users of you code library and/or classes).

On the other hand, the code comments are helpful to understand the internals of your methods. Usually these comments are only read by your colleagues.

Now that the difference is clear we can continue.

As developers we usually ignore or forget the "code comments", but we always try to write some information (even minimum) when is related with the "code documentation", we even have tools to autogenerate the documentation or whine if it's not correct.

Why do we keep forgetting and ignoring the "code comments"? From my point of view there are 2 main reasons:

"It's not needed"

That's what we think when we're writing new code. At the moment the code is always so clear and beautiful that there's no need to document it. Why should we spend time? Who can be so dummy that needs extra info about our code?

Well the dummy guy that will need this comment is usually ourselves. When we come back to this block of code in the future, things will not look so clear and obvious.

"Laziness"

That's the other major reason. The typical "I'm really busy right now, I'll do it later". You known what? If you leave it for later, is almost sure that never will happen.

The lack of proper comments in our code is always going to come back in the future and bite us.

The next day we'll see some tips about how to properly comment our code.

See you.