If Socrates was a Programmer
To Comment or Not to Comment
Should we comment or not? The hottest topic debated over many years among the years by the programmers. Here is an imaginary discussion that gives the answer to the question ” Should comment or not?”
If Socrates had been a computer programmer, he and his students might have had the following
discussion.
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 programmer
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 drach
mas’ 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 encour
age 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 use
ful. 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
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, Cal
licles. I’ve worked on your code and you’re one of the best programmers in the com
pany. 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 hap
pen 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.”
“Cool down, Thrasymachus. Ask Callicles how long he’s been programming.”
“How long, Callicles?”
“Well, I started on the Acropolis IV about 15 years ago. I guess I’ve seen about a dozen
major systems from the time they were born to the time we gave them a cup of hemlock.
And I’ve worked on major parts of a dozen more. Two of those systems had over half a
million lines of code, so I know what I’m talking about. Comments are pretty useless.”
Socrates looked at the younger programmer. “As Callicles says, comments have a lot of
legitimate problems, and you won’t realize that without more experience. If they’re
not done right, they’re worse than useless.”
“Even when they’re done right, they’re useless,” Callicles said. “Comments are less
precise than a programming language. I’d rather not have them at all.”
“Wait a minute,” Socrates said. “Ismene agrees that comments are less precise. Her
point is that comments give you a higher level of abstraction, and we all know that lev
els of abstraction are one of a programmer’s most powerful tools.”
“I don’t agree with that,” Glaucon replied. “Instead of focusing on commenting, you
should focus on making code more readable. Refactoring eliminates most of my com
ments. Once I’ve refactored, my code might have 20 or 30 routine calls without need
ing any comments. A good programmer can read the intent from the code itself, and
what good does it do to read about somebody’s intent when you know the code has
an error?” Glaucon was pleased with his contribution. Callicles nodded.
“It sounds like you guys have never had to modify someone else’s code,” Ismene said.
Callicles suddenly seemed very interested in the pencil marks on the ceiling tiles.
“Why don’t you try reading your own code six months or a year after you write it? You
can improve your code-reading ability and your commenting. You don’t have to
choose one or the other. If you’re reading a novel, you might not want section head
ings. But if you’re reading a technical book, you’d like to be able to find what you’re
looking for quickly. I shouldn’t have to switch into ultra-concentration mode and read
hundreds of lines of code just to find the two lines I want to change.”
“All right, I can see that it would be handy to be able to scan code,” Glaucon said. He’d
seen some of Ismene’s programs and had been impressed. “But what about Callicles’
other point, that comments get out of date as the code changes? I’ve only been program
ming for a couple of years, but even I know that nobody updates their comments.”
“Well, yes and no,” Ismene said. “If you take the comment as sacred and the code as
suspicious, you’re in deep trouble. Actually, finding a disagreement between the com
ment and the code tends to mean both are wrong. The fact that some comments are
bad doesn’t mean that commenting is bad. I’m going to the lunchroom to get another
pot of coffee.” Ismene left the room.
“My main objection to comments,” Callicles said, “is that they’re a waste of resources.”
“Can anyone think of ways to minimize the time it takes to write the comments?”
Socrates asked.
“Design routines in pseudocode, and then convert the pseudocode to comments and
fill in the code between them,” Glaucon said.
“OK, that would work as long as the comments don’t repeat the code,” Callicles said.
“Writing a comment makes you think harder about what your code is doing,” Ismene
said, returning from the lunchroom. “If it’s hard to comment, either it’s bad code or
you don’t understand it well enough. Either way, you need to spend more time on the
code, so the time you spent commenting wasn’t wasted because it pointed you to
required work.”
“All right,” Socrates said. “I can’t think of any more questions, and I think Ismene got
the best of you guys today. We’ll encourage commenting, but we won’t be naive about
it. We’ll have code reviews so that everyone will get a good sense of the kind of com
ments that actually help. If you have trouble understanding someone else’s code, let
them know how they can improve it.”
—————–END OF THE STORY————-
I think this story would have given you the answer to the question “Should we comment or not”. This is taken from the book “CODE COMPLETE” written by Steve McConnell. Every Software Engineer Should read this book at least once. It contains lots of guides with real-time usage which can make you a better programmer.
