Sweet, sweet smell of comments in code?

Extreme Programming breeds overreaction


Arguments rage over the importance of adding comments to your code versus the importance of writing clear code that speaks for itself, thereby potentially eliminating the need for comments. The dichotomy boils down to this: writing comments versus writing self-commenting code, as if comments and clear code are somehow mutually exclusive.

Before I get into the cut and thrust of this debate, it's worth stating that the subject of comments is less of an important issue than writing good code. While comments have value, if the code is crufty and convoluted, adding a few paragraphs of comments - while well intentioned - are only likely to add to the noise.

The Extreme Programming movement, back in its heyday, popularized the notion that comments in code are bad, taking the position that if you see a comment then it must be a "code smell" and you should grab your pair-programming buddy and refactor the stinky code immediately. The term used was "coding by intention" - writing code that so obviously communicates its method and purpose that it doesn't need to be commented.

So instead of this:


int x=0;   // day of month, 0 if not found
for (Rabbit rabbit : warren) { // check for a white rabbit
    if (Color.WHITE.equals(rabbit.getColor()) {
        x=1;   // First day of month,
        break; // so hop out of loop
    }
}
// Show msg indicating start of month or not:
System.out.println( (x==1)?
    "It's the first day of the month!" :
    "Sorry, it isn't the first day of the month."

You have this:

boolean firstDay = isFirstDayOfMonth();
showDayOfMonthMsg(firstDay);

(and the obvious extracted methods...)

Note that isFirstDayOfMonth() isn't called something like checkForWhiteRabbit() because the "how" (or method) of determining whether it's the first day of the month is encapsulated into the method itself. This goes some way towards explaining why these are called methods.

The notion seems reasonable, and in fact it's a good guideline to follow - up to a point. As with many of its practices, XP spoiled a good guideline by taking it to extremes, turning the knob all the way up to 10: comments are a "code smell" and must be refactored out; if you spot a code smell, refactor it immediately.

But however vocally XPers argue against commenting - or over commenting - your code, the opposite camp can argue pretty loudly too.

Here are some of the arguments for comments in code:

  • Months later, someone will look at your unclear or uncommented code, they will go out, buy a shotgun and hunt you down.
  • Clear code conveys the "what" and the "how", but not the "why" - the crucial missing context that comments can and should supply. My personal answer to this argument is - if you'll excuse the book plug: write lightweight use cases (or user stories) and tie them closely to the objects. That gives you the "why" with traceability and a method of driving functional/unit tests from your use cases, for very little extra effort.
  • Sometimes you need to work around an API glitch, or your code steps outside the obvious, and you want to communicate why.
  • If you're writing an API, the public methods need to be liberally commented so, for example, you can give the Javadoc tool something decent to munch on.

Sounds reasonable? Here, then, are some of the arguments for not adding comments:

  • They are not provably correct - if you write a unit test instead of a comment, though, the test is correct. Note this argument is logical bunkum, because a test's pass/fail isn't the same as provable correctness. It's provable passing/failing - also important, but different.
  • A comment in code is a sign that the code isn't clear enough.
  • Comments become out of date because they don't fail at compile- or run-time like out-of-date code.
  • Sometimes comments are copied and pasted along with copied and pasted code. That means the code is then changed but the comments aren't, resulting in comments that essentially tell lies about the code.
  • Comments are often redundant, simply paraphrasing what the code already says ("// increment x").

Clearly, there are compelling arguments on both sides. But you should also be able to see a pattern emerge from the arguments. They're talking about particular conditions when the argument holds true.

So if it's only sometimes vitally important to comment your code or to write clearer code/tests instead of comments, why do the proponents of either side argue so vehemently for their cause? I'll delve further next time.®

Matt Stephens is co-author of Extreme Programming Refactored, which skewers XP like a rodent on a toasting fork.


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