I have lost count of the number of times that I have been asked to work
on a piece of software written by another developer, only to find out
that the code had no comments. What typically follows is hours spent
wading through lines and lines of complex instruction to determine how
the software was intended to work before I could make any
modifications. I can hear the groans, yes it's the old "code
comments" debate that has been going on between software developers
since the first lines of code was punched into a machine capable of
storing and editing of instructions.
In my honest opinion I see no real good reason for the absence of code
comments. The days of programming in a vacuum are long gone,
also are the days of programming software, which is never to be
maintained once it reaches production. There is a strong
probability that any code that you develop today will be reviewed
and/or maintained by someone else tomorrow. Yet, there are still plenty
of developers who believe that this simplistic approach to software
documentation is a hindrance to their productivity and refuse to
comment.
Below are the excuses that I have heard from other software developers when asked why their code has no comments:
1. "I had a deadline to meet and did not have time to add comments."
Adding code comments at the time of writing adds very little to the
overall development time of a project. I would argue that it
actually saves time because it saves the developer having to remember
what they wrote a few days ago when coming back to a previously written
module. Comments will also save hours of work down the line when the
same piece of software is maintained or enhanced. The time required to
add comments should be considering in the original implementation
estimate.
2. "I'll add the comments later after our software is released to production."
Comments are an inherent part of the software implementation process,
and should not be considered as an after thought. Adding code
comments as you develop software is easier than having to go back and
add them later. Greater accuracy of comments is guaranteed if comments
are added while the intended operation of code is fresh in the mind of
the developer. Often is the case that developers rarely go back
and add comments to production code.
3. "Comments slow down my compilation."
Nope! most preprocessors and compilers are optimized to skip comments
when translating code into machine instructions or intermediate
language code. Code comments no more slow down compilation than
adding white space characters between lines of code.
4. "If no-one knows how my software works I'll have job security."
False! If your employer has a need to terminate your agreement, writing
uncommented code will not save your butt. Sure, it'll cost more time
and money having someone else follow your work, but in the long run
your code will get replaced with code that is easier to maintain,
saving time and money overall.
5. "I am just too damn lazy to add comments to my code."
If you cannot take enough pride in your work to write a good piece of
software with comments, which others can continue developing against
after your done, then you should consider another profession and stop
making life difficult for other developers who need to follow you.
6. "I plan on stiffing my employer by creating unmaintainable code and then leaving."
You're not going to hurt your employer, just the poor developer who follows you, which might be me.
The following are all good reasons why code comments are a good thing:
1. Your code can be maintained by someone else after you've moved on.
2. You'll be harassed less by your employer if someone else can work on your code in your absence.
3. Forget what you wrote yesterday? Read your own comments, you should be able to understand them.
4. Comments above classes and methods help break up code and distinguish one method or class from another.
5. Any special circumstances or quirks in the code will be obvious to someone editing your code.
6. Software change requests and bug numbers can be indicated in the code, linking the code with a bug tracking system.
7. Public API code is easier to use by 3rd parties.
8. If you can comment your code then you can demonstrate a greater understanding during code reviews.
Finally, for those of you developing C# or Visual Basic .Net
applications, using Visual Studio 2005, I have created a macro to make
the task of code commenting easier:
1. Download the zip file, containing a VB macro file, from
here.
2. Open the macro explorer in Visual Studio 2005.
3. Create a new macros project.
4. Create a new macro in the project and overwrite the VB code (all
macros are written in VB) with the XmlComments.vb code downloaded in
the zip file.
5. Customize VS.Net by adding a keyboard short cut to the "CommentMe" macro in the new project you just created.
So, what does my macro code do that the regular doc comments built into VS.Net (/// in C#) do not already do?
1. Comments are added above classes, methods and properties, depending
on the current cursor position. This makes for faster development, e.g.
when adding comment, just execute the macro when inside the curly
braces. No need for moving the cursor above the method, property or
class to trigger the built-in doc comments.
2. My macro detects parameter types and adds
cref tags to the parameter comments.
3. Any exceptions used in a method or property are detected and
automatically commented in the comments above the method or property
using the
exception tag.
4. Existing comments are not overwritten by my macro, instead my macro adds missing comment tags to existing comments.
5. When overriding methods and properties from a base class, my macros
code will use the same comment from the base class version.
6. VS.Net adds empty tags when using the built-in doc comments, my macro has a stab at suggesting a default comment.