No Comment

When I interview a new C++ programmer, my favourite question is not about const-correctness or virtual tables, but: "Do you comment your code?". I still ask about virtual tables, but asking about code comments always springs some interesting discussions and gives me a good insight about the level of care the aspiring programmer puts in crafting his code to not only make it correct and fast, but also to make it easy to work with. I witnessed puzzled faces wondering if that was a trick question (yes it is), and one unlucky candidate pushed his luck to a very bold "which good programmer doesn't comment his code!". Me.

I don't know if not commenting my code makes me a good programmer, but it surely forces me to go a long way to make it so my code is as clean and as self-documenting as I can possibly make it.

But I lied: it's not true that I never write any comment, a more precise principle I adhere to as much as possible is:

• Comment only what can't be expressed in code

Which is very little in my experience.

More precisely my adversity to comments stems from the DRY principle:

• Don't Repeat Yourself

Intentions in code should be expressed once and only once: code comments are very often a blatant violation of the DRY principle, which usually leads to several nasty problems and inefficiencies. For once, whenever there is a duplication in code of any form, changes to that bit of code must be done at least twice. Comments are no exception: to be remotely useful they must be kept in sync with the code they describe, but, being us programmers very creative and intelligent people (and lazy), it's guaranteed we will sometimes forget to update comments when we modify, fix, update a bunch of code. A wrong comment is not only useless, it's actually harmful. In a see of green what I'm interested in is the code: that's where the meaning is, that's where the bug is if I'm looking for one. Comments are noise, and often wrong. If the code is so complicated that can't be understood without comments, my suggestion is to rewrite it and make it clear, our fellow workmates will thank us for the extra effort and love.

So when it comes to comments, I follow one guideline very strictly:

• Whenever you feel the need to write a comment, write a method instead

I'm a sucker for code that reads like English, it's self explaining and tells me right there everything I really need to know about itself, in a nice executable form, with no duplication.

An interesting consequence of applying this guideline extensively is that code tends to nicely divide itself in small units of behavior, one per method, that are easy to reuse, further reducing the overall amount of code (that will inevitably spawn a bug at some point). No Comment is for me a powerful incentive to factorize code.

But there's never a free lunch, and very rarely the perfect solution or methodology: I've found out that my style of layering abstractions over abstractions, keeping methods short and easily understandable, makes reading code difficult for a certain class of programmers who need to see the inner details of an algorithm  in order to understand it fully: my style slows them down, since they have to jump back and forth to have the full picture, including details. These programmers are often very bright and you want to put them in the most comfortable position to weave their magic.

It's an issue in my style that I haven't fully resolved, and I'm very open to suggestions here: I believe it's a matter of finding the sweet spot between abstractions and details, and it probably depends on the team and the actual people we have to work with. At the end of the day the goal is the best productivity possible for the whole team.

Post also available at AltDevBlogADay.