Feeds

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

Learn from the shame of Windows 2000

Secure remote control for conventional and virtual desktops

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.

Secure remote control for conventional and virtual desktops

More from The Register

next story
Microsoft boots 1,500 dodgy apps from the Windows Store
DEVELOPERS! DEVELOPERS! DEVELOPERS! Naughty, misleading developers!
Apple promises to lift Curse of the Drained iPhone 5 Battery
Have you tried turning it off and...? Never mind, here's a replacement
Mozilla's 'Tiles' ads debut in new Firefox nightlies
You can try turning them off and on again
Linux turns 23 and Linus Torvalds celebrates as only he can
No, not with swearing, but by controlling the release cycle
Scratched PC-dispatch patch patched, hatched in batch rematch
Windows security update fixed after triggering blue screens (and screams) of death
This is how I set about making a fortune with my own startup
Would you leave your well-paid job to chase your dream?
prev story

Whitepapers

5 things you didn’t know about cloud backup
IT departments are embracing cloud backup, but there’s a lot you need to know before choosing a service provider. Learn all the critical things you need to know.
Implementing global e-invoicing with guaranteed legal certainty
Explaining the role local tax compliance plays in successful supply chain management and e-business and how leading global brands are addressing this.
Backing up Big Data
Solving backup challenges and “protect everything from everywhere,” as we move into the era of big data management and the adoption of BYOD.
Consolidation: The Foundation for IT Business Transformation
In this whitepaper learn how effective consolidation of IT and business resources can enable multiple, meaningful business benefits.
High Performance for All
While HPC is not new, it has traditionally been seen as a specialist area – is it now geared up to meet more mainstream requirements?