There is an adage that if you have nothing nice to say then don’t say anything at all. Good advice for life and when commenting code. Many comments in code don’t say anything, let alone something nice.
I have found that comments can generally be divided into two categories. Firstly, there are comments that only add clutter. Secondly, comments that are used for the wrong reason. I’m sure you have heard the song by Dr Hook about the introverted developer that knows when to use comments, “He don’t say nothing, but baby makes his code talk” (ok, the actual title was “Baby makes her blue jeans talk”, but there just aren’t any great songs about developers!)
I was guilty of bad comments for many years and think it originated from my lecturers while studying. They drummed on the fact that we needed to comment our code, except they didn’t teach us the correct reasons for doing so. Many tools force redundant comments on us. StyleCop, GhostDoc and Javadoc come to mind. Most of the time the comments developers add to satisfy these tools might as well be gobbledygook, as it adds the same value.
// Private variable that holds the number of students private int NumerOfStudents
Not a Crutch
The worst reason for using comments is to compensate for bad design. How many times have you seen a 5000 line class where comments like “Initialisation Section”, “Financial Calculations”, “Database CRUD functions”, etc. are used to divide hundreds of methods into sections? This goes for those 1000 line methods as well.
Instead of adding a comment to a piece of code explaining what it does, rather wrap the code in a method and give the method a name that explains what it does. Instead of having sets of methods divided by comments create new classes that perform the functions.
Comments do not compensate for bad design!
If a variable requires a comment to explain what it holds or is used for, you need to go back to the book of baby variable names and pick a name that explains the function of the variable.
Redundant comments
All projects make use of source control, if your project doesn’t….well then comments are the least of your worries. So why in this day and age do people still add journal comments to code? Just add an explanation as part of your check-in. Some of the new source control tools even show you the check-in comment when you hover over a piece of code.
//Joe Smith 2014-03-03: Method updated to calculate interest from first day public double CalculateInterest(double amount, DateTime startDate)
The same goes for code that is commented out. Why check it in when it just creates scare tissue in your code base? It also has the undesired effect that nobody wants to delete the commented out code as they are unsure why the code is commented out.
Illuminate your code
Use comments to clarify design decisions or to stop future developers from having to learn a lesson you’ve already learnt. As an example, explain that you didn’t use the standard date format conversion function as it was slower than just using standard string functions.
The standard “TODO” type comments also serve a purpose and a few tools use these comments to create lists for you.
When comments start serving a purpose then other developers won’t glance over them as they know it means there is something important. Think before you make a comment, know why are you doing it and does it add value?
If you have some more comments about comments, please leave one.