Inline Comments Should Be Minimized - Not Eliminated

While attending a great SD West session on xUnit Test Patterns and Smells by Gerard Meszaros, I got into a debate with a fellow attendee as to the usefulness of inline comments in code. He lived and died by Kent Beck’s theory that inline comments were simply “deodorant” used to cover up code smells. This attendee stated, matter of factly, that there was never a good time to use inline comments.  While I rarely, if ever, like to contradict Kent Beck, in this instance I have to respectfully disagree.

Don’t get me wrong, I fully understand that the software engineering community often overuses and abuses inline comments. Anytime you need to add inline comments to explain or detail a particular series of logic, it is a good indication that the code should be refactored into a more readable format. However, there are times that inline comments can still be useful. Take for instance, unit tests. I follow the C-I-C pattern in my unit tests (Create - Invoke - Check). Over time I have developed a habit of adding inline comments above each part of the pattern as a visual guide as to what the unit test is doing. Now do I need to see the //Create comment to understand what I am doing when I instantiate an object or two for the purpose of testing? Nope. Is the code easily readable by other developers? Yup. So why do I add the seemingly redundant inline comments to the test?

One reason is that by putting the inline comments into my tests, I am effectively passing on a design strategy to future engineers. I know a lot of good engineers who are poor testers. Writing “good” unit tests is still a relatively rare skill. But when other engineers see me consistently commenting my unit tests with //Create, //Invoke, //Check comments, they will easily be able to recognize the pattern in the code, and it can help them learn strong unit testing strategies without ever talking to me.

This doesn’t just apply to unit tests. Any time you are using a specific design pattern, it doesn’t hurt to add a small amount of inline comments to make it perfectly clear to future engineers what pattern is being implemented. How many of you can recognize a Factory Pattern on sight? How about the Flyweight pattern? The Mediator pattern? Unless you sleep with your GoF or Code Complete books, the odds are that you can’t recognize every pattern when you see it in code. These inline comments help the code become as learning experience to the engineers reading it.

Again, inline comments that are used to explain a confusing snippet of code are bad - that is a sign that the code should be refactored to be more readable. But completely shunning inline comments assumes that every future engineer who touches your code has the same development knowledge as you. The fact is that we are all different in our understanding and knowledge of code, and we can all learn from each other. An inline comment here and there, while not needed, can help share that knowledge among our peers.