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


in reply to Re^4: On comments
in thread On comments

I agree with you. Right up to the point when I don't :) That might sound trite, but it actually reflects reality of my take on this subject. And many others.

I don't consider each separate new thread on this subject here a standalone argument to be won or lost, but rather just another round in an ongoing discussion that comes around again every few months, and has been doing so (for me) for the best part of 30 years. And my position has changed over those years; and still varies depending upon the language I'm using. In general, the higher level the language, the less frequently does the need for comments arise. As Perl is the highest level language I use regularly, I see less reasons here than in most.

But my default position is, and has been for a long time, extremely simple: Don't comment.

It all started from a passing comment [sic] by my first and best mentor in the commercial programming world. He was a mathematician and Fortran programmer. I was working on a fairly involved 6502 assembler project and he was charged with overseeing me and the code I produced, but had no experience of assembler at all; let alone the bits & bytes convolutions involved in interfacing a "toy" 8-bit microcomputer to a very expensive high speed OMR more usually hooked up to mini or mainframe.

He was going though the motions of "reviewing" my code when turned to me and asked: "You do know that comments are optional don't you?" To which I replied, "Of course, but I wanted to make it clear what I was doing.". "You mean, you wanted to make it easy for me to read?". I nodded. "The trouble is, if you comment every line, I have to read every line." He then pointed out several sections of code, essentially while loops, that had a dozen or so nearly identical lines with nearly identical comments. His suggestion was that I replace all those comments with a one or two lines at the top describing the block, but in a Fortran-esque style.

And he was right!

Not only did it save me immense amounts of time coding--especially when it came to re-writing bits to correct bugs. It also saved him loads of time reading. We also found that by commenting in terms of a higher level language, it actually made both writing the code; and verifying it, far, far easier than using English prose. The higher level language was designed for doing that exact job. Unlike English prose.

And the benefit that the default stance of "Don't comment" brings to the table is that you have to justify (to yourself) breaking that stance by adding a comment, rather than the pro-commenters stance of having to justify not commenting. This, IMO, leads to far better commenting, because only those comments that are truly useful get made. And by their rarity, their significance becomes all the more obvious.

Where the reverse stance means that people tend to comment because they think they should, which leads to the significant comments (and often the code) getting "lost in the noise".


Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.