If the Comments Are Ugly, the Code Is Ugly

itwbennett writes "What do your comments say about your code? Do grammatical errors in comments point to even bigger errors in code? That's what Esther Schindler contends in a recent blog post. 'Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must be a nit-picker, or the code won't work ... Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses) indicate that the developer probably didn't understand what he was doing.'"

Comments

Seems reasonable

[jgtg32a]

Comments do require a bit of effort and time commitment. If you are willing to spend time on the comments your most likely going to spend more time working the code itself.

Re:The comment may also be complex..

[Marillion]

I've always subscribed to the theory that the code explains WHAT a program should do clearly enough that even a computer understands it.

Comments should fill in the gaps and answer the questions of WHY and HOW. For example, if I'm using a common pattern or idiom, I like to highlight that. I like to use the Delegation Pattern when doing SAX parsing of XML in Java. Rather that explain what the Delegation Pattern is about, I'll just cite the pattern name, add a link, and explain the nuances of that particular implementation and move on.

Re:Long-winded comments can be very useful

[dkleinsc]

Often better than including the full explanation inline is: "Proof that this works can be found ...". Yes, it's one more reference to look up, but some of the algorithms in, say, Knuth, are long and complex proofs that really will interrupt your code reading if included inline.

A lot of good comments answer one of these questions:
  - Why couldn't this be simplified?
  - What special case is this trying to handle?
  - This looks weird. Why is it right?
  - What expectations are we demanding from elsewhere in the code?

A situation where I find myself asking any of those questions and no comment is present can be nightmarish.

I agree, with reservations

[JustNiz]

From 30 years of developing software, I've found time and time again that it actually does seem that people who don't know or care about the difference between "their" and "they're" are also too sloppy, unintelligent or just not anal enough to write clean, supportable and robust code.

However I feel we do need to make more allowance than the article's author did for people who did not learn English as a first language.

Or a management failure

[Moraelin]

Or it could be just an indication of a management failure.

A couple of years ago I was brought in to save a project that was hopelessly behind schedule and getting nowhere. Pretty quickly I got the idea that whenever I check something into CVS, it gets re-checked by a really helpful girl there, richly decorated with comments. (Now I do comment classes and methods extensively, as well as places where higher elven magic was used, but I do _not_ write stuff like that now I'm iterating through a node's children. If you need a comment to understand that "for" loop, then there's something deeper wrong with my code.)

But, anyway, stuff like a line that said "if (currentNode.isRootNode())" had been decorated with the obviously helpful comment "// when the current node is the root node". I'm still at a loss as to what extra info is conveyed by that comment, since just reading the code out loud gets you almost the same sentence and definitely the same meaning.

And it went like that for every single line. Every single assignment, trivial loop, etc, was dutifully duplicated in that line's comment.

Turns out, they were asked to comment their code extensively, and judged basically by quantity. So she was just abiding by the rules.

OT on long comments

[FrankSchwab]

Being as this is devolving into a discussion of long comments, rather than a discussion of whether mispellings in comments indicate a lack of attention to detail in coding, I thought I'd throw in something.

To maintain some sense of topicality: I don't particularly agree with the blog post. As someone with good English skills, I've read a lot of code where the English language skills (and thus spelling and grammar in the comments) of the coder are below mine, but their skills in the computer language at issue are superior to mine. Frankly, there's a far greater relationship between accuracy of the comments (do they actually describe what the code does) and the quality of the code, than there is between spelling, subject-verb agreement, and number of spaces after a period and the quality of the code. This relationship does follow the blog author's contention about coders needing to be nit-pickers.

Occasionally in my coding, I write a novel in the function header. Generally, this isn't because I don't understand the problem so much as its because I do understand the problem. I've spent hours or days understanding the problem, and the particular necessray function that implements the solution, and I don't relish spending hours or days 6 months in the future remembering what I know today. The interesting thing is that, most of the time, the novel is multiple times larger than the function - 50 lines of comment for a 20 NCLOC function isn't unheard of.

In my specialty (embedded systems, with especially tight hardware integration), there are functions that need to be written that deal with extraordinarily complex situations. Many times, the bare code tells a misleadingly simple tale - "do this, that, and the other thing", rather than (as Russ Nelson pointed out above)

but to explain all the other code that could have been written, but wasn't

. Oftentimes, the novel is there to explain all the ways to trip up in this 20-line function - e.g. unspecified hardware dependencies, subtle system dependencies, unobvious race conditions. Sometimes its there to explain why, no matter how wrong the function appears, it is actually correct.

Re:The comment may also be complex..

[mjschultz]

I've gotten into the habit of commenting first, coding second. It is especially useful in complex systems.

I find that if I write the high level logic in comments of all the functions I'm going to write, it helps me find where I should break out repeated logic and solidifies the design. Once everything has been commented, I can go back and write the code.

This lets me know what the variables are going to be and can name them appropriately (why name it `i` when I can call is `block_index`). I don't lose the big picture of what needs to get done. It gives me targets to meet and stopping points at the end of the day (a sense of accomplishment and goals for tomorrow is *really* nice). Future coders can read my comments and see what I was thinking (this has actually happened to me). As a bonus, I can worry more about corner cases as I'm writing the code instead of creating corner cases to worry about later.

I've done it with a Flash memory interface, O/S memory manager, and a kernel module. Each time I've finished, even if it isn't the best code in the world, I know that if the next person reads the comments, they'll know what I was thinking.

Better code all around.

Comments are for future maintainers

[cwills]

The whole purpose of comments is to explain the code so that future maintainers (including the author of the code) can easily understand what is going on. If done right, a maintainer can pick up a module and come up to speed as to what the code does, why it does it, and any thing else that might trip them up. Comments need to capture the developers thoughts from when the code was being designed and written. The reasoning and ideas behind an algorithm that took several months to design cannot be truly captured with a 3 line comment and 25 lines of code.

I feel that comments can be broken into four types:

1. Boiler plate front matter. These are the comments that are required by the coding standards of the shop. Usually contains copyright notices, author's name, list of changes, etc.
2. Specification and reference comments. A list of the external references, such as the formal specification for the code, a bibliography for the algorithms used, etc.
3. Block comments. These should describe the intent of a larger block of code. The reader should be able to take all the block comments from a program and have a good understanding what the entire program does. Block comments should describe the what and why. Block comments should also describe any gotchas, or special conditions that the maintainer needs to be aware of.
4. Line comments. Should describe the purpose of a small number of statements. Line comments should not merely echo the action of the code itself, but describe what is happening and how the particular action relates to the rest of the program.

   i += 4; /* Increment i by 4 */ BAD comment
   
   i += 4; /* Ignore the first 4 fields */ Better

Roman Bridges

[Dragoness Eclectic]

Oh please. Inexactitude is *not* the same thing as not understanding why something works at all. We can build miles-long bridges *specifically* because we understand the underlying physics, and anyone who built a bridge without understanding the physics of why it stood under load would be drummed out of the industry.

I am assuming you refer to the modern physics that we are all so proud of. Let me tell you that in Europe, whenever you get a real serious flooding on a major river, only one kind of bridge survives with no bruises at all: Roman bridges. They are 2000 years old, but they're still up. The crap we're building today won't be up in 2000 years, I can bet on it. Look at the mess with the bay bridge, down twice in 50 years!!!! Ah ah ahah! Kuddos to modern engineering.

That would be because the Romans had some engineering, but not the equations we have today, so they over-engineered their bridges for safety because they knew they couldn't calculate the exact, optimal configuration for the expected loads and stresses. Over-engineering is a good thing if you don't have to account to the bean-counters. The George Washington Bridge across the Hudson River was also over-engineered because they didn't know the exact tolerances, and it has held up rather well.