Feeds

Comment judiciously, refactor if needed, avoid the 'f' word

Learn from the shame of Windows 2000

High performance access to file storage

Comments can be abused as easily as any other tool or technique. You know comments - and, indeed, the project - have become dysfunctional when you start to see gripes and swearing, or flames concerning either the code or the individual who wrote the code.

When the Windows 2000 source was leaked a few years back the code was, to Microsoft's embarrassment, liberally infused with the bitter side swipes and literary headbutts of some deeply frustrated programmers. There were also plenty of "fucks", "shits" and "craps".

So code comments do have their dark side and there are plenty of arguments against commenting.

But is that enough to regard comments something that must be wiped out or to demonize comments so they're as hated as software errors, excessive unpaid overtime and heavyweight upfront documentation?

As I described previously, agile has a drop-in replacement for code comments: coding by intention. This is an important concept in test-driven development, but it also makes perfect sense to give your methods and variables nice clear names. But does this really eliminate the need for comments? Getting into the XP mindset, a comment is a code smell and must be refactored immediately, usually into a separate method with a purportedly self-documenting name.

In the obsessive quest to remove all comments from your code, though, it's possible to flatten out a perfectly readable method into a dozen or so one-line methods, each of which literally does one thing.

Why is this bad? Taking Java as an example, indentation is conventionally used to indicate the structure of code constructs: while loops and so forth. On the other hand, calls between methods in a single class are not so clear - I've worn out my F7 key thanks to continually doing Alt-F7 in IntelliJ IDEA to see the code that points to a method.

Visually, a class is one dimensional - a series of methods starting at the top of the screen and so on down. Glancing at the code, the interaction between all the methods isn't obvious. Reducing your code to a linear collection of single-line methods eliminates the visual self documentation that clear, grouped-together, indented code gives you. In the quest for clear code, you've inadvertently littered your code with virtual GOTOs.

So separate the teeny, tiny methods into their own classes, I hear you say. But now you've got a profusion of tiny classes without clear responsibilities: neither desirable nor maintainable. And this approach is also dangerously close to functional decomposition, an approach to design that really doesn't map well to object-oriented languages.

I'm all for breaking complex code into smaller, clearer methods by the way, but pushing the dial all the way to 10 can have negative consequences too. If this is truly the case, and overdoing method decomposition can actually make code less clear, then coding by intention may not be the drop-in replacement for code commenting that the agile gurus would have us believe.

It's worth summing up with a couple of guidelines - though, as with all guidelines, use your judgment and deviate at will. The name of a method should be the "what" of the method; the body of the method should be the "how", of course; and the comment at the top of the method should be the "why".

Finally, sometimes it's all about how the advice is presented. So, rather than the extreme "comments in code are evil" view, a fairer way to say it would be "if in doubt, add in a comment". But do question the need to add a comment, and refactor or rethink the code if it needs it. Just don't overdo the comments, as comments must be maintained along with the code.

Matt Stephens is co-author of Extreme Programming Refactored: The Case Against XP and Agile Development with the ICONIX Process: People, Process, and Pragmatism.

High performance access to file storage

More from The Register

next story
Windows 8.1, which you probably haven't upgraded to yet, ALREADY OBSOLETE
Pre-Update versions of new Windows version will no longer support patches
Android engineer: We DIDN'T copy Apple OR follow Samsung's orders
Veep testifies for Samsung during Apple patent trial
OpenSSL Heartbleed: Bloody nose for open-source bleeding hearts
Bloke behind the cockup says not enough people are helping crucial crypto project
Microsoft lobs pre-release Windows Phone 8.1 at devs who dare
App makers can load it before anyone else, but if they do they're stuck with it
Half of Twitter's 'active users' are SILENT STALKERS
Nearly 50% have NEVER tweeted a word
Windows XP still has 27 per cent market share on its deathbed
Windows 7 making some gains on XP Death Day
Internet-of-stuff startup dumps NoSQL for ... SQL?
NoSQL taste great at first but lacks proper nutrients, says startup cloud whiz
US taxman blows Win XP deadline, must now spend millions on custom support
Gov't IT likened to 'a Model T with a lot of things on top of it'
Microsoft TIER SMEAR changes app prices whether devs ask or not
Some go up, some go down, Redmond goes silent
prev story

Whitepapers

Securing web applications made simple and scalable
In this whitepaper learn how automated security testing can provide a simple and scalable way to protect your web applications.
Five 3D headsets to be won!
We were so impressed by the Durovis Dive headset we’ve asked the company to give some away to Reg readers.
HP ArcSight ESM solution helps Finansbank
Based on their experience using HP ArcSight Enterprise Security Manager for IT security operations, Finansbank moved to HP ArcSight ESM for fraud management.
The benefits of software based PBX
Why you should break free from your proprietary PBX and how to leverage your existing server hardware.
Mobile application security study
Download this report to see the alarming realities regarding the sheer number of applications vulnerable to attack, as well as the most common and easily addressable vulnerability errors.