Feeds

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

Learn from the shame of Windows 2000

Choosing a cloud hosting partner with confidence

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
Netscape Navigator - the browser that started it all - turns 20
It was 20 years ago today, Marc Andreeesen taught the band to play
Sway: Microsoft's new Office app doesn't have an Undo function
Content aggregation, meet the workplace ... oh
Sign off my IT project or I’ll PHONE your MUM
Honestly, it’s a piece of piss
Return of the Jedi – Apache reclaims web server crown
.london, .hamburg and .公司 - that's .com in Chinese - storm the web server charts
Chrome 38's new HTML tag support makes fatties FIT and SKINNIER
First browser to protect networks' bandwith using official spec
Admins! Never mind POODLE, there're NEW OpenSSL bugs to splat
Four new patches for open-source crypto libraries
Torvalds CONFESSES: 'I'm pretty good at alienating devs'
Admits to 'a metric ****load' of mistakes during work with Linux collaborators
prev story

Whitepapers

Forging a new future with identity relationship management
Learn about ForgeRock's next generation IRM platform and how it is designed to empower CEOS's and enterprises to engage with consumers.
Cloud and hybrid-cloud data protection for VMware
Learn how quick and easy it is to configure backups and perform restores for VMware environments.
Three 1TB solid state scorchers up for grabs
Big SSDs can be expensive but think big and think free because you could be the lucky winner of one of three 1TB Samsung SSD 840 EVO drives that we’re giving away worth over £300 apiece.
Reg Reader Research: SaaS based Email and Office Productivity Tools
Read this Reg reader report which provides advice and guidance for SMBs towards the use of SaaS based email and Office productivity tools.
Security for virtualized datacentres
Legacy security solutions are inefficient due to the architectural differences between physical and virtual environments.