It’s pretty common for developers to disagree on the role of comments in source code, sometimes in a rather vehement manner. I think at least part of the problem comes from a fundamental misunderstanding, in that most developers simply don’t explain well what they mean when they talk of well-commented code. I believe there are multiple types of code comments, of varying value in different stages of a project and I also suggest that when disagreements come to pass over comments, it’s largely because developers are using the same word to describe very different things. Here are the types of code comments I commonly see and what purposes they serve well.
- Outlining comments – comments that are written before any code is written. These are simply placeholders that form a narrative of the algorithm being used. I rarely do this. Outlining comments often are more properly known as lies once a project is in production and has been changed extensively.
- TO DO comments – comments are written as placeholders while code is being written to remind developers of tasks not yet accomplished. Frequently, tools such as Visual Studio .NET will help you find these items. These should be deleted when the task(s) mentioned therein are completed. I use these a lot, in combination with failing or ignored unit tests, to highlight code that needs completion.
- Clarity comments – these are the comments that your programming instructor told you to place in your code, that you promptly stopped doing once you got a real job. Clarity comments should be in place for sections of code that are a bit difficult to understand for whatever reason. I try not to use these, preferring to simply fix the code, but sometimes it’s unavoidable, like in any case where Regex is involved.
- Documentation comments – these comments are left in a file to be harvested (hopefully automatically) by an external system. .NET XML comments are a great example of this. I hate these sort of comments with the burning flame of a thousand suns, not only because they make code more unreadable, cause me to have to make a change in multiple places, and frequently have annoying syntax, but also because auto-generated documentation is almost universally a bunch of hot garbage masquerading as something more useful than a “Just Say No” pamphlet at a Grateful Dead concert. It’s even better when it’s simply a header on a file or stored procedure, because nothing says loving like making me scroll for something trivial like a list of what parameters go into a procedure call so I can know “Brian corrected a spelling error on 4/23/2002”. Go team Brian. I admit to having a strong opinion on this one.
- Apology comments – I make these more often than I’d like. I classify apology comments as any sort of comment where the developer is apologizing for something horrid in the code. Examples I’ve seen (or written – you be the judge) are:
1
2
3
4
5// I’m going to hell for writing this. However, I turned in my resignation today and you are reading this code, so you’re already in hell
// Admittedly, I don’t helpfully name variables when drunk
// Yes, it’s a pile of crap. No, you can’t fix it. Please affix your name and date here after your failed attempt
// F$#% it! I’ll be a plumber instead
// Yes, it’s spaghetti code – I’m practically Italian now.
After thinking through numerous conversations I’ve had around code comments, I believe that a large percentage of conflicts about what sort of commenting should happen is largely because we are using one word to describe vastly different concepts. I think that should change, and propose that my nomenclature be adopted until someone sane and reasonable comes up with a better one.