http://www.perlmonks.org?node_id=740521


in reply to Why no comments?

One reason these commenting discussions get so difficult is that good commenting is really a product of programming experience, and sometimes history. Depending on experience, one person's commenting on goals of the code is another person's commenting on mechanics.

Consider a block of code consisting of a while loop with internal variables named $high, $low, $mid. I think most experienced programmers skimming the code would assume that the loop is some kind of binary search algorithm. They might appreciate (at most) a very short comment saying #binary search right above the start of the while loop, but anything more than that would be annoying. On the other hand, if there was something weird about the use of a binary search in that context or it really wasn't a binary search, then any of the following comments might be appreciated:

But each of those comments requires a great deal of context and experience even to construct. A programmer who doesn't know what a binary search algorithm looks like is hardly going to know that he or she needs to comment their code when it looks like one but isn't.

On the other hand, I'm sure some of us can remember when we were first learning the ideas behind a binary search. Grasping each step of the algorithm was painful and we very much appreciated our professor or text book explaining each step of the algorithm and why it was done that way.

As a further thought, what does and doesn't need to be commented changes over time even for the software industry as a whole. Before the discussion of patterns became widespread, it would have been impossible to comment code using a visitor pattern with a one liner #process foo using visitor pattern.

Best, beth