What is the best approach for inline code comments?

Question

We are doing some refactoring to a 20 years old legacy codebase, and I'm having a discussion with my colleague about the comments format in the code (plsql, java).

There is no a default format for comments, but in most cases people do something like this in the comment:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

the proposed format for future and past comments that I want is:

// {yyyy-mm-dd}, unique_author_company_id, comment

My colleague says that we only need the comment, and must reformat all past and future comments to this format:

// comment

My arguments:

• I say for maintenance reasons, it's important to know when and who did a change (even this information is in the SCM).
• The code is living, and for that reason has a history.
• Because without the change dates it's impossible to know when a change was introduced without open the SCM tool and search in the long object history.
• because the author is very important, a change of authors is more credible than a change of authory
• Agility reasons, no need to open and navigate through the SCM tool
• people would be more afraid to change something that someone did 15 years ago, than something that was recently created or changed.
• etc.

My colleague's arguments:

• The history is in the SCM
• Developers must not be aware of the history of the code directly in the code
• Packages gets 15k lines long and unstructured comments make these packages harder to understand

What do you think is the best approach? Or do you have a better approach to solve this problem?

Answer 1

General Comments

I am a great believer in comments are for why (not how). When you start adding comments about how you fall into the problem that nothing is enforcing that comments be maintained in relation to the code (the why will usually not change (the why explanation may be enhanced some over time)).

In the same way date/authorInfo does not gain you anything in terms of why the code was done this way; just like the how it can degenerate over time because there is no enforcement by any tools. Also the same information is already stored in the source control system (so you are duplicating effort (but in a less reliable way)).

Going through the arguments:

I say for maintenance reasons, it's important to know when and who did a change (even this information is in the SCM).

Why. Neither of these things strike me as important to maintaining the code. If you need to talk to the author it is relatively simple to find this information from source control.

The code has life for that reason had an history.

History is stored in source control.
Also do you trust that the comment was written by that person. How comments tend to degrade over time so this kind of history becomes unreliable. Source control systems on the other hand will maintain a very accurate history and you can accurately see when comments were added/removed.

Because without the change date it's impossible to know when a change was introduced without open the SCM tool and search in the long object history.

If you trust the data in a comment.
One of the problems with this kind of things is that the comments become incorrect in relation to the code. Back to the correct tool for the job. The source control system will do this correctly without need for intervention from the user. If your source control system is a pain then maybe you need to either learn how to use it more appropriately (as that functionality is usually easy) or if does not support it find a better source control system.

because the author is very important, a change of authorx is more credible than a change of authory

All authors (apart from yourself) are equally credible.

Agility reasons, no need to open an navigate the SCM tool

If your source control tool are that burdensome you are wither using it incorrectly or (it is more likely) you are using the wrong set of tools to access the source control system.

people would be afraid of change something that someone did 15 years ago, than someting that was receantly made ...

If code has lasted 15 years then it is more likely to be more solid then code that has only lasted 6 months without needing review. Stable code tends to stay stable, buggy code tends to get more complex over time (as the reason it is buggy is the problem is not as simple as first thought).

Even more reason to use source control to get information.

The history is in the SCM

Yes. Best reason yet.

Developers must not be aware of history of the code directly in the code

If I really need this information I will look it up in source control.
Otherwise it is not relevant.

Packages gets 15k lines long and unstructured comments this packages harder to understand

Comments should be a description of why you are doing something anyway.
Comments should NOT be describing how the code works (unless the algorithm is not obvious).

Answer 2

I strongly support your colleague. You won't get by without looking at the SCM anyway if you want to understand why something was changed unless you keep the old code in a comment.

If the code is too complex to be understood without writing tons of comments, I'd suggest investing you energy into refactoring to make the code readable/maintanable without tons of comments.

After all, you hire programmers, not story tellers ;-)