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

Learn from the shame of Windows 2000


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.


Other stories you might like

  • Will Lenovo ever think beyond hardware?
    Then again, why develop your own software à la HPE GreenLake when you can use someone else's?

    Analysis Lenovo fancies its TruScale anything-as-a-service (XaaS) platform as a more flexible competitor to HPE GreenLake or Dell Apex. Unlike its rivals, Lenovo doesn't believe it needs to mimic all aspects of the cloud to be successful.

    While subscription services are nothing new for Lenovo, the company only recently consolidated its offerings into a unified XaaS service called TruScale.

    On the surface TruScale ticks most of the XaaS boxes — cloud-like consumption model, subscription pricing — and it works just like you'd expect. Sign up for a certain amount of compute capacity and a short time later a rack full of pre-plumbed compute, storage, and network boxes are delivered to your place of choosing, whether that's a private datacenter, colo, or edge location.

    Continue reading
  • Intel is running rings around AMD and Arm at the edge
    What will it take to loosen the x86 giant's edge stranglehold?

    Analysis Supermicro launched a wave of edge appliances using Intel's newly refreshed Xeon-D processors last week. The launch itself was nothing to write home about, but a thought occurred: with all the hype surrounding the outer reaches of computing that we call the edge, you'd think there would be more competition from chipmakers in this arena.

    So where are all the AMD and Arm-based edge appliances?

    A glance through the catalogs of the major OEMs – Dell, HPE, Lenovo, Inspur, Supermicro – returned plenty of results for AMD servers, but few, if any, validated for edge deployments. In fact, Supermicro was the only one of the five vendors that even offered an AMD-based edge appliance – which used an ageing Epyc processor. Hardly a great showing from AMD. Meanwhile, just one appliance from Inspur used an Arm-based chip from Nvidia.

    Continue reading
  • NASA's Psyche mission: 2022 launch is off after software arrives late
    Launch window slides into 2023 or 2024 for asteroid-probing project

    Sadly for NASA's mission to take samples from the asteroid Psyche, software problems mean the spacecraft is going to miss its 2022 launch window.

    The US space agency made the announcement on Friday: "Due to the late delivery of the spacecraft's flight software and testing equipment, NASA does not have sufficient time to complete the testing needed ahead of its remaining launch period this year, which ends on October 11."

    While it appears the software and testbeds are now working, there just isn't enough time to get everything done before a SpaceX Falcon Heavy sends the spacecraft to study a metallic-rich asteroid of the same name.

    Continue reading
  • Rise in Taiwanese energy prices may hit global chip production
    National provider considering cost increase of 8%, which could be passed on to tech customers

    Taiwan's state-owned energy company is looking to raise prices for industrial users, a move likely to impact chipmakers such as TSMC, which may well have a knock-on effect on the semiconductor supply chain.

    According to Bloomberg, the Taiwan Power Company, which produces electricity for the island nation, has proposed increasing electricity costs by at least 8 percent for industrial users, the first increase in four years.

    The power company has itself been hit by the rising costs of fuel, including the imported coal and natural gas it uses to generate electricity. At the same time, the country is experiencing record demand for power because of increasing industrial requirements and because of high temperatures driving the use of air conditioning, as reported by the local Taipei Times.

    Continue reading
  • Tech companies ready public stances on Roe v. Wade
    Some providing out-of-state medical expenses, others spout general pro-choice statements

    Several US tech companies have taken a stance or issued statements promising healthcare-related support for employees following the Supreme Court's ruling to overturn Roe v Wade last Friday.

    A Supreme Court draft opinion that was leaked in February provided advanced warning of the legal eventuality, giving companies plenty of time to prepare official positions and related policies for employees.

    Without proper policies in place, tech companies could put themselves at risk of "brain drain" as employees become tempted to relocate to states where abortion access is readily available or to companies that better support potential needs as healthcare in the US is more often tied to an employer than not.

    Continue reading

Biting the hand that feeds IT © 1998–2022