Lakhasly

To Comment or Not to Comment
Comments are easier to write poorly than well, and commenting can be more damaging than helpful. The heated discussions over the virtues of commenting often sound
like philosophical debates over moral virtues, which makes me think that if Socrates
had been a computer programmer, he and his students might have had the following
discussion.
The Commento
Characters:
THRASYMACHUS A green, theoretical purist who believes everything he reads
CALLICLES A battle-hardened veteran from the old school—a “real” programmer
GLAUCON A young, confident, hot-shot computer jock
ISMENE A senior programmer tired of big promises, just looking for a few practices
that work
SOCRATES The wise old programmer782 Chapter 32: Self-Documenting Code
Setting:
END OF THE TEAM’S DAILY STANDUP MEETING
“Does anyone have any other issues before we get back to work?” Socrates asked.
“I want to suggest a commenting standard for our projects,” Thrasymachus said.
“Some of our programmers barely comment their code, and everyone knows that
code without comments is unreadable.”
“You must be fresher out of college than I thought,” Callicles responded. “Comments
are an academic panacea, but everyone who’s done any real programming knows that
comments make the code harder to read, not easier. English is less precise than Java or
Visual Basic and makes for a lot of excess verbiage. Programming-language statements
are short and to the point. If you can’t make the code clear, how can you make the
comments clear? Plus, comments get out of date as the code changes. If you believe an
out-of-date comment, you’re sunk.”
“I agree with that,” Glaucon joined in. “Heavily commented code is harder to read
because it means more to read. I already have to read the code; why should I have to
read a lot of comments, too?”
“Wait a minute,” Ismene said, putting down her coffee mug to put in her two drachmas’ worth. “I know that commenting can be abused, but good comments are worth
their weight in gold. I’ve had to maintain code that had comments and code that
didn’t, and I’d rather maintain code with comments. I don’t think we should have a
standard that says use one comment for every x lines of code, but we should encourage everyone to comment.”
“If comments are a waste of time, why does anyone use them, Callicles?” Socrates
asked.
“Either because they’re required to or because they read somewhere that they’re useful. No one who’s thought about it could ever decide they’re useful.”
“Ismene thinks they’re useful. She’s been here three years, maintaining your code
without comments and other code with comments, and she prefers the code with
comments. What do you make of that?”
“Comments are useless because they just repeat the code in a more verbose—”
“Wait right there,” Thrasymachus interrupted. “Good comments don’t repeat the
code or explain it. They clarify its intent. Comments should explain, at a higher level
of abstraction than the code, what you’re trying to do.”
“Right,” Ismene said. “I scan the comments to find the section that does what I need
to change or fix. You’re right that comments that repeat the code don’t help at all
KEY POINT32.3 To Comment or Not to Comment 783
because the code says everything already. When I read comments, I want it to be like
reading headings in a book or a table of contents. Comments help me find the right
section, and then I start reading the code. It’s a lot faster to read one sentence in
English than it is to parse 20 lines of code in a programming language.” Ismene
poured herself another cup of coffee.
“I think that people who refuse to write comments (1) think their code is clearer than
it could possibly be, (2) think that other programmers are far more interested in their
code than they really are, (3) think other programmers are smarter than they really
are, (4) are lazy, or (5) are afraid someone else might figure out how their code works.
“Code reviews would be a big help here, Socrates,” Ismene continued. “If someone
claims they don’t need to write comments and are bombarded by questions during a
review—when several peers start saying, ‘What the heck are you trying to do in this
piece of code?’—then they’ll start putting in comments. If they don’t do it on their
own, at least their manager will have the ammo to make them do it.
“I’m not accusing you of being lazy or afraid that people will figure out your code, Callicles. I’ve worked on your code and you’re one of the best programmers in the company. But have a heart, huh? Your code would be easier for me to work on if you used
comments.”
“But they’re a waste of resources,” Callicles countered. “A good programmer’s code
should be self-documenting; everything you need to know should be in the code.”
“No way!” Thrasymachus was out of his chair. “Everything the compiler needs to
know is in the code! You might as well argue that everything you need to know is in
the binary executable file! If you were smart enough to read it! What is meant to happen is not in the code.”
Thrasymachus realized he was standing up and sat down. “Socrates, this is ridiculous.
Why do we have to argue about whether comments are valuable? Everything I’ve ever
read says they’re valuable and should be used liberally. We’re wasting our time.”