If Socrates was a Programmer

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.

YOU CAN BUY  THE BOOK USING THE BELOW LINK

Sree Hari Sanjeev

The founder and CEO of Wisdom Overflow. His enthusiasm and effort has taken the blog to next level. You will be motivated just by taking a look at his daily schedule.