To Comment or Not to Comment
Comments are easier to write poorly than well, and commenting can be more damaging than helpful."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."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?"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."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.""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."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.""Comments are useless because they just repeat the code in a more verbose--"
"Wait right there," Thrasymachus interrupted.Socrates asked.