Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Re: On comments

by BrowserUk (Pope)
on Dec 19, 2010 at 23:52 UTC ( #877922=note: print w/replies, xml ) Need Help??


in reply to On comments

(Most)Comments are worse than useless. They are a drag on both the original and future programmers time and effort.

Show me some of your comments + the associated code, and I'll re-write the code to make the comments superfluous(*).

(*)It doesn't always work. Some comments are useful. But rarely.


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^2: On comments
by Tux (Abbot) on Dec 20, 2010 at 08:38 UTC

    I both agree and disagree. I notice that the more experienced a programmer is, the more useful the comments in the code are.

    A good programmer codes in a way that comments on how the current code works doesn't need any comments, nor do the variable names or their purpose(s).

    What does need comments is the reason why the current code uses a specific algorithm or - maybe double as important - why a certain other, maybe more obvious, algorithm was not used.

    Those are the most valuable types of comments in code IMHO. Even if the original reason turns out not to be true after 15 years of hardware development or different compiler optimizations.


    Enjoy, Have FUN! H.Merijn

      If you look above, I was very careful to say "(Most)"; and "Some comments are useful.".

      My contention is that they are far rarer than most people believe. Please also see Programming *is* much more than "just writing code".


      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 didn't miss that. What I'm (also) trying to say is that (new) programmers have to learn along the way what comments are most useful 5 years from now. When you start programming, you have a really wrong approach in that aspect learned at school.


        Enjoy, Have FUN! H.Merijn
Re^2: On comments
by Ratazong (Monsignor) on Dec 20, 2010 at 08:22 UTC

    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")

      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.

Re^2: On comments
by raybies (Chaplain) on Dec 21, 2010 at 23:28 UTC

    I have to confess the most frequent comment I use is:

    #Note2Ray: FIX ME!

    Heh.

    --Ray

      Yes. I too have left a bunch of similar annotations in source code scattered around Europe down the years. More in hope than expectation, like forlorn messages in bottles. My wife says I'm unfixable.


      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.
Re^2: On comments
by pemungkah (Priest) on Dec 28, 2010 at 10:21 UTC
    Please head on over to perl5db.pl, and fix that up so it doesn't need comments. I'll wait. :)

    That was a big project - about a year - and all I did was comment the code. Why? Because nobody other than a very few people understood the debugger. Reading that code with no comments is sort of like hearing half a phone conversation, as the debugger is really just the Perl side of the execution-time hooks that make debugging possible. The comments clarify the things that are happening elsewhere that are important to the the debugger code that's just been called from someplace else. That contextual info is important - and it can't be in the code; it has to be in the comments. Yes, you could switch back and forth between the debugger source and the Perl source, but you'd have to understand the Perl core pretty well. With comments, you can just read and understand in much less time with much less effort.

    Compare the 5.004 debugger to the 5.8.8 one to see the difference between the uncommented source and the commented. I think it was worth doing, as (among other things) Devel::ebug and the beginnings of the debugger tests in the Perl core tests came out of that. I firmly believe it was because the stuff you should "just get from the code" was finally laid out, explained, and made possible to follow.

    I also believe that nearly anyone who's basically familiar with Perl can now read the debugger source and actually get something out of it other than a headache, even if it's a resolution to never ever write code like that.

    Comments, as I mentioned, are not meant to tell you what the code can tell you itself; they are meant to tell you what decisions went into putting that code there in the first place, and the context in which these decisions made sense. As in the kernel bug noted, the reason for the decision is sometimes more important and considerably more complex than the code itself is. When a few characters make the difference between a root exploit and secure code, put in the comment!

    Writing comments is writing; if the comments are good, then they communicate an arc of logic from point start to finish. The combination of the comments and the code should tell you more than either could alone. If they don't then the comments are wasted space - but should be condensed, corrected, and made to communicate, not simply discarded!

    The comments and code conflict? There are several possible reasons, but one important possibility is that there really was a disconnect between the desire and the implementation, and that the code is actually wrong. It may be functioning and passing its tests, but it may nonetheless not be what was actually intended. It may be very hard to find out what was really wanted - and the code and comments don't help - but the fact that they conflict communicates something important that the code alone would not and cannot. If you simply strip the comments and then look at the code, you've thrown away data. Never a good idea when you're looking at code you don't know well (meaning that you know what was wanted, what it's doing, and why).

    I honestly find an approach that says "never" comment or "always" delete comments suspect; it's as if the programmer had decided that they didn't like else clauses. Sure, you can write code that's functionally equivalent without them, but you've made a choice that deliberately makes the code's primary job - communicating to the next programmer - more difficult, and I think that's a bad choice.

    Comments are as integral a part of the language, and if you've decided never to use them, you really should think about that, and be sure it's not (for instance) compensating for feelings of insecurity. "I'm so good I don't need comments! Really I am!"

    I prefer to know that I need comments some places, and I make sure I put them in at those places. I don't think I'm not as good because I comment; I think I'm more considerate and better cognizant of my abilities by doing so. Maybe the next programmer really will be so good he or she doesn't need comments. Let's hope the one after the decommenter is as good as the decommenter thinks he or she is.

    Know your audience, and be honest and pragmatic. Not every programmer is going to be as brilliant as every other. You're not going to be as brilliant every day. Make sure the average programmer (and you) will be able to read the code with the comments and get as much out of it as the brilliant one can without the comments. This is eminently possible, and worth it, in my opinion.

      Sorry, but bad comments do not make up for bad code.

      All of this:

      Can be replaced by:

      { local( $trace, $single, $^D ); ($evalarg) = $evalarg =~ /(.*)/s; # Untaint # $usercontext built in DB::DB @res = eval "$usercontext $evalarg;\n"; # '\n' for nice recur +sive debug }

      Not only is it shorter and clearer, it is safer. As tchrist points out in the above code:

      # 'my' would make it visible from user code # but so does local! --tchrist

      You've gone to great verbosity to explain how the variables: $otrace, $osingle, $od, are used to prevent the user code from messing with the debugger's internal state. Completely missing the fact that by storing copies in those localised globals, it is just as likely that the user code will mess with those variables as the originals. And if they do, the code will be restoring the messed with values over the top of the untouched original values.

      Whereas if you simply localise the original globals, they'll be restored when the block exits regardless of what the user does. And the need for all the code-concealing and confusing comments just goes away.

      I can see from what you've done to perl5db.pl that we'll never agree. That's fine. Some people like marmite, some don't.

      But, the last four paras of your post above show me that you've either not read Programming *is* much more than "just writing code"., or you have and still think you can justify your position by concluding that those with the opposed viewpoint are either too lazy or too arrogant to comment. And that is just plain not the case.

      I rarely comment because I've found over the years that the vast majority of comments tell me nothing more than the code does. But worse, as above, the comments attempt to persuade me stuff that is just flat out wrong.

      Even your point that "Not every programmer is going to be as brilliant as every other." totally misreads that reasoning. For example, any programmer unfamiliar with local--which is a larger portion of modern Perl programmers--will, from reading your comments above, get entirely the wrong idea about what it does and how it works. And will go away with entirely the wrong impression because of those bad comments.

      If however, there were no comments, they would have had to have gone to the documentation, and read up about the local keyword and learnt what it really does.

      Like I said. Bad comment are worse than no comments. And most comments are bad. Even those by people who think they write good ones.


      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 have read Programming *is* much more than "just writing code". and it's clear that we come from diametrically opposite points about comments, which is fine. If we were working on the same team we'd need to find a compromise. I'm going to use the rhetorical tool I mentioned a while back in the node about "agressive argument" (Re: What is "aggressive" argument?) to defuse the discussion, which feels a little heated to me: since it is at least partially a matter of taste, this is one of those arguments that can't be definitively "finished" or "won", only abandoned - and I think that this is probably the proper point for me to do that. This is not saying "I'm right" or "you're wrong", just "we're not going to agree about this, I think".

        It's possible that I've simply not clearly stated the assumption I'm working from: comments don't actually affect the logic of the program, Smart::Comments aside - but they do affect the logic of the programmer, and what he or she will decide to do.

        Intentions, political considerations, external dependencies, and other similar factors that have nothing to do with the local code that's on the page (but everything to do with the context in which it was developed and in which it must run) are important, and that not making sure they are known at the exact point where further decisions need to be made in the source code will increase the chances of those decisions being wrong, perhaps catastrophically so.

        I personally think that comments are the best way to do that: right at the code that was affected by the external circumstance (some other obscure code called it, in the case of the debugger, or that variable really does have to be zero or we have a remote root exploit in the Linux kernel source). Is there a better way to communicate that kind of thing at the point of decision: at the place in the code that might be changed without a signpost that doing so would be Bad? Remember, I'm not asking you to make the code clearer; I'm asking you to make the context clearer. What's the best way to do that?

        I think we agree that this non-local-code context is important, and difficult to communicate effectively. I would be very interested to hear what ways you use to get all that messy not-code stuff across to "the next victim".

        (Edit: spoiler that shows the comments from perl5db.pl wasn't working for me, but is now...go figure. Minor wording changes for clarity.)

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (2)
As of 2020-02-23 08:06 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What numbers are you going to focus on primarily in 2020?










    Results (102 votes). Check out past polls.

    Notices?