Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things

Re^3: On comments

by BrowserUk (Pope)
on Dec 20, 2010 at 09:05 UTC ( #877972=note: print w/replies, xml ) Need Help??

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

I disagree with you here.

Of course, you, and the OP, have every right to your opinion and conclusions. just as do I. I've had this debate many times down the years and no one has yet convinced me to change my mind.

I laid out my reasoning here in a meditation: Programming *is* much more than "just writing code"., so I won't repeat them in this thread.

I have on occasion succeeded in changing the opinions of others. Whilst those occasions have been rare, there is a common theme to those occasions of my success. And that is the challenge I made above.

Every pro-comments advocate I ever encountered has agreed that there are "good comments" and "bad comments". But what they will rarely ever do is back up their conceptual support for good comments with real life examples that they are prepared to back.

On those rare occasions when I have persuaded people to offer up (real life) examples for discussion, per my challenge to the OP, they have often been persuaded by my re-writes of the examples that the comments are redundant. But the examples do have to be real-life, not contrived.

As I said above, it doesn't always work. We can all come up with a (usually contrived) example of a comment that cannot be better handled with code.

Personally, I think that people become enamoured with the idea of "good comments", but few if any ever live up to their own ideals of what is actually a "good comment". Hence my challenge.

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.

Replies are listed 'Best First'.
Re^4: On comments
by mr_mischief (Monsignor) on Dec 24, 2010 at 12:12 UTC

    In a lower-level language like assembly comments can be very useful in ways that would be unnecessary in higher-level languages. I know that's only relevant in a rare case, because assembly (at least assembly written by hand) itself should be a rare case. I also agree that the "good comment" that so many support is probably more rare than they suspect. I can think of one situation I already mentioned in this thread that was from real life in which a good comment could have really helped.

      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.

        I agree with you about commenting being the exception rather than the rule. I also agree with comments being small, seldom, and to the point being helpful. I also see the advantage to sometimes using a higher-level programming language to comment a lower-level one. However, I don't see how using a higher-level language rather than English prose would help in every case.

        I don't see, for example, restating the code helping someone to understand why it is important to zero-fill or zero-extend the high 32 bits of a 64-bit register when working in 32-bit mode on a hybrid 32-bit and 64-bit machine for security purposes. An explanation of why something is done really doesn't come from doing it again in a different way. When you really must explain why, explaining how does no help. Hardware vagaries and minute details of domain knowledge can be restated in many programming languages, but the reasoning behind the code is still a separate thing from the code itself.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://877972]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (4)
As of 2021-04-10 12:45 GMT
Find Nodes?
    Voting Booth?

    No recent polls found