Sunday, March 13, 2011

Source Code Comments Revisited

I have to admit I don't get much traffic on this blog - usually a few hits per day, according to Feedjit. That's why I was pleasantly surprised when I saw a steady stream of comments earlier today. Some of them were submitted here on, but most went to the discussion on Since I can't possibly reply to every single comment, here is a summary response.

First of all, I'd like to thank everyone who agreed with my view of automated unit tests as a perfectly good substitute of source code comments (of course, unit tests are much much more than a replacement for comments!). I also appreciate the folks who submitted constructive criticism and shared their personal rules of thumb for writing comments.

Some readers took offence on my use of terms like "cohesion", "coupling", and "cyclomatic complexity", calling them buzzwords. My friends, if these terms are just buzzwords to you, then you clearly are missing some important trends in our industry. If you are writing objects with hundreds of methods that pertain to dozens different responsibilities, or if your thousand-line functions have so many if-else statements it makes you dizzy, then no amount of source code comments will hide one simple fact: your code is bad and is in dire need of refactoring.

One often-repeated mistake was that I am advocating against ALL source code comments. This is simply not true, and if you read the blog post through the end, you will see a pretty funny example of a very legitimate comment one programmer left in his code.

Speaking of examples - I got a few posts saying they are "stupid", "straw-man", and not real. Well, I don't even know what to say... There are just two examples in my blog post, and both are taken verbatim from the StackOverflow discussion called "What is the best comment in source code you have ever discovered".

To all people who questioned my credibility, I am happy to say that I have been a professional programmer for over 16 years, used more programming languages than I care to remember, and was involved in the maintenance of large codebases. I do code reviews on a regular basis, and I always enjoyed respect of my colleagues. True, my current job title is no longer a "programmer", and I've been coding in C# exclusively for the last several years, but make no mistake - I am no "dabbler" when it comes to software development.