What is the best approach for inline code comments?

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:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment
</code>
<code>// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment </code>
// 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:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// {yyyy-mm-dd}, unique_author_company_id, comment
</code>
<code>// {yyyy-mm-dd}, unique_author_company_id, comment </code>
// {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:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// comment
</code>
<code>// comment </code>
// 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?

4

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).

3

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 😉

Trang chủ Giới thiệu Sinh nhật bé trai Sinh nhật bé gái Tổ chức sự kiện Biểu diễn giải trí Dịch vụ khác Trang trí tiệc cưới Tổ chức khai trương Tư vấn dịch vụ Thư viện ảnh Tin tức - sự kiện Liên hệ Chú hề sinh nhật Trang trí YEAR END PARTY công ty Trang trí tất niên cuối năm Trang trí tất niên xu hướng mới nhất Trang trí sinh nhật bé trai Hải Đăng Trang trí sinh nhật bé Khánh Vân Trang trí sinh nhật Bích Ngân Trang trí sinh nhật bé Thanh Trang Thuê ông già Noel phát quà Biểu diễn xiếc khỉ Xiếc quay đĩa Dịch vụ tổ chức sự kiện 5 sao Thông tin về chúng tôi Dịch vụ sinh nhật bé trai Dịch vụ sinh nhật bé gái Sự kiện trọn gói Các tiết mục giải trí Dịch vụ bổ trợ Tiệc cưới sang trọng Dịch vụ khai trương Tư vấn tổ chức sự kiện Hình ảnh sự kiện Cập nhật tin tức Liên hệ ngay Thuê chú hề chuyên nghiệp Tiệc tất niên cho công ty Trang trí tiệc cuối năm Tiệc tất niên độc đáo Sinh nhật bé Hải Đăng Sinh nhật đáng yêu bé Khánh Vân Sinh nhật sang trọng Bích Ngân Tiệc sinh nhật bé Thanh Trang Dịch vụ ông già Noel Xiếc thú vui nhộn Biểu diễn xiếc quay đĩa Dịch vụ tổ chức tiệc uy tín Khám phá dịch vụ của chúng tôi Tiệc sinh nhật cho bé trai Trang trí tiệc cho bé gái Gói sự kiện chuyên nghiệp Chương trình giải trí hấp dẫn Dịch vụ hỗ trợ sự kiện Trang trí tiệc cưới đẹp Khởi đầu thành công với khai trương Chuyên gia tư vấn sự kiện Xem ảnh các sự kiện đẹp Tin mới về sự kiện Kết nối với đội ngũ chuyên gia Chú hề vui nhộn cho tiệc sinh nhật Ý tưởng tiệc cuối năm Tất niên độc đáo Trang trí tiệc hiện đại Tổ chức sinh nhật cho Hải Đăng Sinh nhật độc quyền Khánh Vân Phong cách tiệc Bích Ngân Trang trí tiệc bé Thanh Trang Thuê dịch vụ ông già Noel chuyên nghiệp Xem xiếc khỉ đặc sắc Xiếc quay đĩa thú vị
Trang chủ Giới thiệu Sinh nhật bé trai Sinh nhật bé gái Tổ chức sự kiện Biểu diễn giải trí Dịch vụ khác Trang trí tiệc cưới Tổ chức khai trương Tư vấn dịch vụ Thư viện ảnh Tin tức - sự kiện Liên hệ Chú hề sinh nhật Trang trí YEAR END PARTY công ty Trang trí tất niên cuối năm Trang trí tất niên xu hướng mới nhất Trang trí sinh nhật bé trai Hải Đăng Trang trí sinh nhật bé Khánh Vân Trang trí sinh nhật Bích Ngân Trang trí sinh nhật bé Thanh Trang Thuê ông già Noel phát quà Biểu diễn xiếc khỉ Xiếc quay đĩa
Thiết kế website Thiết kế website Thiết kế website Cách kháng tài khoản quảng cáo Mua bán Fanpage Facebook Dịch vụ SEO Tổ chức sinh nhật