What is the best approach for inline code comments?
Posted
by
d1egoaz
on Programmers
See other posts from Programmers
or by d1egoaz
Published on 2012-11-07T20:53:33Z
Indexed on
2012/11/07
23:13 UTC
Read the original article
Hit count: 374
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?
© Programmers or respective owner