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


in reply to Re: On comments
in thread On comments

I disagree with you here.

Comments have one big advantage over the code: they are written to be read by humans. And they are usually on a higher level of abstraction.

I sometimes have to read through thousands of lines of code in search for an error. And that is usually code I have never seen before, but where I only have a rough idea what should happen. So I pass through the code, and focus on reading the comments - till I find possible locations of the error. Only then I look at the code of these locations in detail. Typically, I then compare the code of the "probably error location" with older versions of the same file - and also focus on the comments first - to get the idea why something was changed.

The approach above works well most of the times.

Of course that the depends on the quality of the comments. They need to give you an idea what the coder wanted to do. There are many types of comments that are useless ... possible you, BrowserUk, are referring to things like

if ($i > 0) # check if $i is greater than zero
which I agree to be harmful: they waste time and give no benefit - and even worse(!): they create the mentality of "comments are useless" in the mind of some developers. I hate reading their code ;-/

Sometimes code and comments are not aligned or even contradicting. In my experience, those places are more likely to contain errors than others: it is a sign that a developer made some change in a hurry - and if he had no time for adding a comment, he probably hadn't time to think deep enough on the side-effects of the change (and most probably the code was not reviewed either ...). So even outdated comments are (in some kind) helpful for finding errors...

All the best, Rata (who thinks comments are a really useful "tool")

Replies are listed 'Best First'.
Re^3: On comments
by BrowserUk (Patriarch) on Dec 20, 2010 at 09:05 UTC
    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.

      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.