The Importance of Commenting Code

I recently read this article on commenting code: Is There a Correct Way to Comment Your Code? by Erik Dietrich.  The opinion that “clean code needs no comments” was mentioned.  No.  I disagree.  Comments are helpful.  If a software product is successful then it will be in use for many years.  Programmers unfamiliar with the old code will need to quickly find the spots in the code that need to be changed to fix problems or to add new features.  This activity is called "software maintenance."  Complex technical code is full of equations.  Complex equations are meaningless to programmers and comments are needed to explain the purpose and workings of the equations.  (Complex equations are usually provided to programmers by systems engineers or R&D scientists.)

Complex code can benefit from comments that provide a concise design description.  These design comments might be concentrated at the start of the software module, or they might be scattered among the methods within the software module.

The primary tool for software maintenance is the grep tool.  The least of comments is a keyword in the code that can be caught with grep.  For example, imagine you are ordered to modify Capability_101 in order to add  a new Capability_102 to the old code.  As a code maintainer you need the code that implements the old capability tagged with a comment that says "Capability_101" so the grep tool can find it.

To say well written code needs no comments is foolishness.

Robert

I have written about comments in code before:

Self Documenting Code and Ecclesiastes October 13, 2013

http://canrightonsoftwareandprogramming.blogspot.com/2013/10/self-documenting-code-and-ecclesiastes.html

Software Maintenance and Variables  March 16, 2014

http://canrightonsoftwareandprogramming.blogspot.com/2014/03/software-maintenance-and-variables.html