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

Related posts about java

Related posts about c#