Dear Dick, thanks for sharing your experience.

I can fully understand in the days of ASM and COBOL, without comments, tracing through the code would be a hell of an experience. Glad the team did it perform the due diligence with proper commenting and enabled the code to be maintainable up till today.

These codes due to the nature of how it is written, although can evolve, but has to evolve slowly. Any code changes, not only need to ensure the logic is correct (which can be tested), but also ensure the comment is fully in sync (which can’t be tested but only can be manually eye-ball checked and rectified).

With newer language, we like to embed most of the context into the code itself. Codes should be structured to the smallest component possible where each section should be self-explanatory itself, whereby its function/class name represents clearly its purpose.

With such careful work, the need to explicitly comment on each small section of code becomes unnecessary.

However, what I have often seen is, some coder might conveniently write a much longer function that performs multiple things. Hence instead of spending time breaking into smaller parts, it then has to have some comments that explain its purpose.

But I agree, totally eliminating comments is still not possible today, due to the various reasons I mentioned in my articles. However, one should minimize doing so unless it is unavoidable. The comment is a way to state “Sorry my code doesn’t explain well what and why it is intended to do, please read my comment”.

I fully agree with this quote

“Always code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live.” (source)

The easily angered person will be super mad if seeing a comment that differs from the code. The best way to prevent that is to embed everything in the code as much as possible and avoid comments that can easily misrepresent the code.