Comment or not comment?

“It is clear that at some level comments should be helpful. To think differently would be to assume that the clarity of the program does not depend on how much information about it is already known to the person reading the program. B. Sheyl. ”
Characters:
FRASIMAH An inexperienced purist of theory who believes in everything that reads.
CALLICLE Battle-hardened representative of the old school - “real”
programmer.
GLAVKON A young, self-confident, energetic programmer.
ISMENA Experienced developer, tired of loud promises and just
wanting to find a few working techniques.
SOCRATES A wise experienced programmer.

Mise en scene:
Completion of the daily group meeting
- Does anyone want to discuss anything else before we return to work? - asks Socrates.
“I want to offer a commenting standard for our projects,” says rasimah. - Some of our programmers hardly comment on their code, and everyone knows that the code is unreadable without comment.
“You must be even less experienced than I thought,” Kallikl replies. - Comments are an academic panacea, and anyone who wrote real-world programs is aware that comments make reading the code more difficult, rather than easier. Natural language is less accurate than Java or Visual Basic, and suffers from redundancy, whereas programming language operators are laconic and fall into the sly eye. If someone cannot write clear code, will he be able to write clear comments? In addition, comments become obsolete with code changes.
Trusting outdated comments, you dig a hole for yourself.

“I completely agree,” Glavkon joins the conversation. - Generously commented code is harder to read, because in this case you have to read more. Few
that I have to read the code, so I need to read a bunch of comments too!
“Wait a minute,” inserts his two drachmas of Yemen, setting a cup of coffee.
- Of course, comment abuse is possible, but good comments.
worth its weight in gold. I had to accompany the code as with comments,
and without them, and, if I had a choice, I would prefer the first option. I do not think that
we need a standard forcing to write one comment for every x lines
code, but to encourage all programmers to comment on the code does not hurt.
“If comments are a waste of time, why does everyone use them, Callikl?” - asks Socrates.
- Or because such is the requirement, or because the person read somewhere about
the use of comments. No programmer who has ever thought about this has concluded that comments are useful.

- Yemen believes they are useful. It has been accompanying your code for three years without
comments and someone else's code with comments. You have already heard her opinion. What are you
say this?
“Comments are useless because they simply repeat the code in a more verbose ...”
“Wait,” Thrasimah interrupts Kallikla. - good comments
Do not repeat the code and do not explain it. They explain his purpose. Comments should explain the programmer's intentions at a higher level of abstraction than the code.
“True,” Yemen agrees. “If I'm looking for a snippet that I need to change or correct, I look at the comments.” Comments that repeat the code are actually useless, because everything is already said in the code itself. When
I read the comments, I want them to look like the table of contents of the book. Comments should help me find the right section, and after that I will start reading
code. It is much faster to read one sentence in a regular language than to analyze 20 lines of code in a programming language.
Yemen pours himself a second cup of coffee.
')
- It seems to me that people who refuse to write comments, A) think that
their code is clearer than it could be, B) believe that other programmers are much more interested in their code than it actually is, C) think that other programmers are smarter than they really are, D) are lazy or E) are afraid , what
someone else will know how their code works.
“In this sense, code reviews would be very helpful, Socrates,” continues Yemen.
“If someone claims that there is no need to write comments, and he receives a lot of questions during the review - if several colleagues ask him at once:" What happens in this fragment of your code? "- he starts writing comments. If the programmer does not reach it himself, his supervisor will be able to get him to write comments.
“I’m not saying, Callicl, that you are lazy or afraid that someone else will understand your code.” I worked with your code and I can say that you are one of the best.
programmers of the company. But be a little kinder, eh? It would be easier for me to accompany your code if you wrote comments.

“But this is a waste of time,” Callickle does not give up. - The code of a good programmer should be self-documenting: everything that other programmers need to know should be in the code itself.
- Not! - Thrasymachus jumps up from the chair. - The code already has everything you need
know the compiler! With the same success it would be possible to say that everything that other programmers need to know is already in the binary executable file! If a
if only we were smart enough to be able to read it! Information that
what the programmer was going to do, in the code no.
Thrasymah notices that he jumped up and sits down.
- Socrates, this is unthinkable. Why do we argue about the importance of comments? In all
The books I read say that comments are useful and should not be saved. We waste time.
- Calm down, Thrasymachus. Ask Kallikla how long he has been programming.

“Indeed, how long, Callicl?”
- Well, I started with the Acropolis IV system about 15 years ago. I think that I witnessed the birth and death of about a dozen major applications. And in a dozen projects, I worked on major components. Two of these systems included more than half a million lines of code, so I know what I'm talking about. Comments are completely useless.
Socrates glances at a younger programmer.
“As Kallikl says, there are a lot of problems with comments,
and you will not understand it until you gain more experience. If you comment
the code is illiterate, comments are not just useless - they are harmful.
“They are useless even if the code is correctly commented,” Callicles says.
- Comments are less accurate than a programming language. Personally, I think that
better not to write them at all.

“Wait,” says Socrates. - Yemen agrees that comments are less
accurate, but she claims that comments raise the programmer to more
high level of abstraction, and we all know that abstraction is one of the most
effective tools at our disposal.
“I disagree with that,” says Glavkon. - We should concentrate
not on the comments, but on the readability of the code. When refactoring, most
my comments disappears. After refactoring my code may include 20
or 30 method calls that do not need any comment.
A good programmer is able to determine the purpose of the author by the code itself; to that
What is the use of reading about someone's goal, if it is known that the code contains an error?
Glavkon falls silent, satisfied with his contribution to the conversation. Callicles nods.
“Looks like you never had to change someone else’s code,” Yemen says.
Kallikl pretends that he was very interested in the tiles on the ceiling.

“Why don't you try reading your own code six months or a year after writing it?” You can develop both a code reading skill and a skill.
his commenting. No one forces you to choose one thing. If you are reading a novel, you may not need chapter titles. But when reading technical
books you probably would like to be able to quickly find what you are looking for.
Then I would not have to go into over-focus mode and read
hundreds of lines of code to find two lines that I want to change.
“Well, I understand that the ability to quickly view the code would be convenient,” says Glavkon. He saw some of Ismen’s programs, and they did not leave him indifferent. “But what about the other statement of Kallikla - that
comments become outdated as code changes? I program only a couple
years, but even I know that nobody updates their comments.

“Well, yes and no,” says Yemen. - If you consider comments inviolable, and the code is suspicious, you have serious problems. In fact, the discrepancy between the comment and the code usually indicates that it is incorrect.
both. If any comments are bad, it does not mean that the commenting itself is bad. I'll pour myself another cup of coffee.
Yemen leaves the room.
“My main objection to comments is,” Callickle states, “is
that they spend resources.
- Can you suggest a way to minimize the time for writing comments? - asks Socrates.
“Designing methods on pseudo-code, converting pseudo-code into comments and writing the corresponding code,” says Glavkon.
“OK, it will work if the comments do not repeat the code,” Kallikl says.
- Writing a comment makes you think better about what your
code, says Yemen, returning with a new cup of coffee. - If comments
writing is hard, it means that the code is bad or you don’t understand it well enough. In both cases, you have to work on the code yet, so the time spent on commenting it does not go away - it points you to the work you need.
“All right,” Socrates sums up. “I don’t think we still have questions.” It seems that Yemen today was the most convincing. We will encourage commenting, but we will not treat it ingenuously. We will perform
code reviews for everyone to understand which comments are really helpful. If a
If you have problems understanding the code of another programmer, tell him how he can improve it.

Steve McConneld