Feeds

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

Learn from the shame of Windows 2000

Build a business case: developing custom apps

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.

Boost IT visibility and business value

More from The Register

next story
NO MORE ALL CAPS and other pleasures of Visual Studio 14
Unpicking a packed preview that breaks down ASP.NET
KDE releases ice-cream coloured Plasma 5 just in time for summer
Melty but refreshing - popular rival to Mint's Cinnamon's still a work in progress
Leaked Windows Phone 8.1 Update specs tease details of Nokia's next mobes
New screen sizes, dual SIMs, voice over LTE, and more
Another day, another Firefox: Version 31 is upon us ALREADY
Web devs, Mozilla really wants you to like this one
Put down that Oracle database patch: It could cost $23,000 per CPU
On-by-default INMEMORY tech a boon for developers ... as long as they can afford it
Mozilla keeps its Beard, hopes anti-gay marriage troubles are now over
Plenty on new CEO's todo list – starting with Firefox's slipping grasp
Apple: We'll unleash OS X Yosemite beta on the MASSES on 24 July
Starting today, regular fanbois will be guinea pigs, it tells Reg
prev story

Whitepapers

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.
The Essential Guide to IT Transformation
ServiceNow discusses three IT transformations that can help CIO's automate IT services to transform IT and the enterprise.
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.
How modern custom applications can spur business growth
Learn how to create, deploy and manage custom applications without consuming or expanding the need for scarce, expensive IT resources.
Build a business case: developing custom apps
Learn how to maximize the value of custom applications by accelerating and simplifying their development.