What is the best approach for inline code comments?
- by d1egoaz
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?
