WHY I COMMENT MY CODE

I was reading an article (http://ardalis.com/when-to-comment-your-code) and it got me thinking about the subject, which is near and dear to my heart.

Over the years I've worked on a lot of projects, some for only a few days others spread out over years.  I've produced a lot of helper programs, implemented huge honking scripts and programs in a wide variety of languages over a wide range of platforms.  I've even managed large chunks of code in legacy systems spanning thousands of files.  I've worked in C, Objective-C, C++, Java, SQL, Bash, Ksh, Shell, Batch, Visual Basic, Tcl/Tk, Clearcase triggers, etc...  I've worked on Windows NT through Windows 7, Several Flavors of Linux including ones with Real-Time, Solaris, HP-UX, Powermax, Powerhawk, Lynx, some older flavors of Macintosh, VXWorks, etc...

I remember a day when a coworker was modifying a script to run on a new platform and asked me for some help.  It took a few minutes to figure out what the script was doing, I saw a few places for improvement, figured out the bug she was running into  and work out a solution.  As I was reading through the code I commented that it was a good script and she should consider sharing it with the department to which she responded "You do know you wrote this script, don't you?"  It occured to me that if it wasn't already in my coding style it would have been very difficult for me to figure out what the script was doing.  It was truly unfair to have created this huge program and then expect someone else to maintain it after I had lost interest (usually within a day or so).  I made sure that I left the program well commented before handing it back.

The idea that well-written code doesn't need comments is laughable.  This might fly if you are writing a tiny program, but once you start a project of any real scale - a few hundred thousand lines of code, written in various languages, various coding styles, maintained over a few decades by different companies... Even if you are writing a small program that someone else is going to use, and probably modify a few years down the line when your favorite language is no longer the defacto standard around the office and an intern needs to make a change... It is your duty to make sure that the code is well documented with sprinkled comments.

I consider comments to be bread crumbs that will aid a developer in understanding my code.  I like to strictly follow a coding standard; it doesn't really matter too much which one, but you should follow a consistent coding standard.  If you don't have one I like to do the following:
   - each file should have a header section that describes what the file is doing at a high level.
      //    - provide a revision history section, each entry is on one line
      // REVISION HISTORY
      // DSM  3Dec2012 added support for new signal types including COUNTS and 2-Byte floats
      // DSM  7Dec2012 moved signal information to a seperate class
   - provide a list of features you would like to add at some point, along with priority for implementation
      // TO-DO LIST
      // HIGH   move initialization data to an external file
      // LOW    move printing functionality to a seperate class
   - functions should contain header information that describe what the function is going to do
   - code should frequently comment what you are trying to do (at a high level)
   - if you are not using a tool to do versioning of your code you should provide change tracking in your code (which lines were touched by change number 5?)

If your compile environment supports any kind of documentation you should be using that as well... so for Visual Studio you should be using the XML style documentation that will allow for tool-tips when you mouse over a class or variable.

A lot of people dislike comments because they feel they can lie.  This is a maintenance issue, and when discovered the comments should be updated appropriately.  This is not a reason to do away with the comments entirely.  If anything it's a call for following better coding standards on updating comments.

It doesn't matter how clean you think your code is, some day an intern will attempt to make a change and if you don't give him a few breadcrumbs to follow he will fail.  When he fails it will not be his fault for not understanding your idiosyncratic coding style.  It will be your fault for not living up to the unspoken contract all paid developers have with their employers to write good and maintainable code.

Look at my coding samples for further examples of the minimum level of coding that should be acceptable.  Your code needs to be maintainable.