Beefy Boxes and Bandwidth Generously Provided by pair Networks DiBona
Pathologically Eclectic Rubbish Lister
 
PerlMonks  

No Comment

by awkmonk (Monk)
on Apr 23, 2003 at 13:26 UTC ( #252535=perlmeditation: print w/ replies, xml ) Need Help??

This thought/rant recently arose whilst editing a large program.

How much trust should you have in comments?

The problem I had was easy to fix, but the code it was in had been copied from elsewhere along with embedded comments that no longer applied. So I spent a quiet half hour checking out comments throughout the code, only to find that the most applicable one was right at the start, describing the programs functionality (and even that was wrong - parameters in/out etc).

The 'cut and paste' culture of the development has spread inaccurate or irrelevant comments over the whole system, to the point now that they can/should be ignored. Descriptive naming of fields and functions will normally provide a far better clue as to the functionality than these comments.

It wouldn't be too bad but I've seen this happen time and again across lots of different development teams (and no doubt been responsible for a few as well). Problems arise when you pick up a piece of code to fix/change part of it. Following the logic flow is easy enough (usually), but for the most part that requires reading the code - not the comments.

 

And so this leads me to 4 levels of generalisation:

1. The code does exactly what the comment say's it does so look elsewhere for your bug.

    Good: Can skip through a routine quickly to the appropriate parts. Bad: Some very large assumptions are made.

2. Comments are there to help if the code, or the reason for the code isn't obvious.

    Good: You can ignore comments around most of the 'obvious' code. Bad: Still relying on them for difficult code.

3. Comments should be treated as a work of fiction until proved otherwise.

    Good: Might give you a hint - but you'll still have to read the code to check it. Bad: Now you have to read the code and a description.

4. Comments are the work of the devil, put there to fool you. Ignore them at every turn and rely solely on code. 

    Good: You'll always know exactly what's going on.  Bad: May take a long time when the description was right under your nose.

 

Breath in for 10, hold for 10, and breath out for 10.

Now I've calmed down about that, I'd like to share my thoughts on dealing with the little rascals. 

The only sensible approach that I've found is to apply each rule in turn and to treat comments as if they are code. Fix the broken ones, only put them in when it's necessary, and remove redundant ones. Oh, and to only apply these rules to the areas of code that I touch.

Remember - Comments are for life, not just Christmas.

Thanks for letting me get that off my chest.


'I think the problem lies in the fact that your data doesn't fit my program'.

edited: Wed Apr 23 13:58:30 2003 by jeffa - added readmore tag

Comment on No Comment
Re: No Comment
by dragonchild (Archbishop) on Apr 23, 2003 at 13:44 UTC
    Excellent statements. Personally, I ignore most comments as the work of the Devil and merely read the code. If I can't read the code, I assume no-one else can (as I'm the strongest Perl developer where I am). In those cases, if I can get away with it, I rewrite the code so that it is its own comments. (Then I remove the Devil's ones. *grins*)

    ------
    We are the carpenters and bricklayers of the Information Age.

    Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

    Please remember that I'm crufty and crochety. All opinions are purely mine and all code is untested, unless otherwise specified.

On commenting your code
by merlyn (Sage) on Apr 23, 2003 at 14:09 UTC
    The code itself should be clear enough to denote the algorithm being used.

    However, while coding the algorithm, there are almost always assumptions used and conclusions reached by the programmer. You've all had that while you're coding... those thoughts like "Oh, this could be undef here" or "We must ensure that @foo is initialized before getting here" or "This will work for small lists, but blows up on big lists."

    That's what belongs in the comments. Capture those thoughts, so that someone else can recreate your insights.

    First, the reader of the code three months from now isn't necessarily in the same brainspace as you, and may not realize the same assumptions.

    Second, in three months, you will not be in the same brainspace either. Trust me on this one.

    So, comments should capture the insights and presumptions. The code should clearly express the algorithm on its own.

    Just a thought, from someone who has been programming for 30 years, including re-writing code of others far too often, and pounding my head against the desk saying "WHAT were they THINKING?" {grin}

    -- Randal L. Schwartz, Perl hacker
    Be sure to read my standard disclaimer if this is a reply.

      I agree wholeheartedly.

      I'd like to clear up one issue though...

      My gripe comes as a long suffering maintenance programmer. Who, likewise, for the last nearly 20 years I have spent a great deal of time working on existing code covering many languages rather than the far less often 'writing shiny new stuff'. It's the comments in these old routines that I always view with suspicion.


      'I think the problem lies in the fact that your data doesn't fit my program'.

Re: No Comment
by hardburn (Abbot) on Apr 23, 2003 at 14:10 UTC

    With well-written code, comments (which I consider seperate from the overall documentation, e.g. POD) are often unnecessary. For instance, probably all the CGIs I've written over the past year have a set_params() sub that (surprise!) takes in the CGI input params. It is almost always simply some form of:

    use CGI qw(:standard); sub set_params { my %fields; $fields{foo} = param('foo') || 0; $fields{bar} = param('bar') || 0; $fields{baz} = param('baz') || 0; return %fields; }

    I used to mix in some validation, but I'm trying to force myself to do that in a seperate sub.

    A maintenance programmer looking at the above can know exactly what parameters are being input. No comments necessary. Occasionally, there are some hoops to jump through, in which case a sprinkling of comments is needed.

    POD, IMHO, is for telling what the overall program/module does. Which is why I don't really like the =for comment method of multi-line comments.

    Having a boatload of comments is a good indicator of poor code. Hint: if I have to run your code through B::Deparse just to get rid of your comments and save my sanity, your code probably sucks. Those thousand-dollar "source code obfuscation" tools have got it all wrong--leaving massive numbers of comments in place is a great way to protect your source code :)

    ----
    I wanted to explore how Perl's closures can be manipulated, and ended up creating an object system by accident.
    -- Schemer

    Note: All code is untested, unless otherwise stated

Re: No Comment
by toma (Vicar) on Apr 23, 2003 at 14:13 UTC
    I was taught this same lesson by a firmware programmer who didn't want to read the documentation for the hardware that I had designed. He just wanted to look at my schematics!

    I like to have one comment at the top of each file that says what the program or module is supposed to do. I also like to comment my bugs or poorly written code. I can tell that the code is okay when all of the comments are gone and I can still easily read the code.

    If the code is a module that is intended to be used more than once, writing the pod documentation is still a good idea. This is different from code comments, though. If the module is well-written, it probably won't be subjected to cut-and-paste, it will get used properly.

    It should work perfectly the first time! - toma

Re: No Comment
by Anonymous Monk on Apr 23, 2003 at 15:39 UTC
    Comments should describe what the code is intended to do in the larger context of the subroutine/module/application; the details of implementation may not need comments unless the code achieves its goal in a peculiar manner. Comments like this are useless:
    # Check each element of the array vs. the supplied pattern.
    This, on the other hand, is useful information:
    # Eliminate items that can't be processed.
    Why you are doing something matters more than what you are doing, every time.

    It is true that in other people's code you will sometimes (for larger and smaller values of "sometimes") find code and comments that don't match, or useless comments like those above.

    If you are responsible for the maintenance of the code, it is your responsibility to not only fix any bugs, but to make the comments useful. This will consume a little more time, but you will have recorded a solid foundation to work from when you (or the next person) come back to the code later.

    Having added comments that are accurate to the best of your ability to understand the code, even if the comment is

    # XXX I can't tell what this next section is doing.
    adds to the value of the code.

    It is always your responsibility to comment your own code in the most useful manner possible; if you must cut and paste, at least indicate that you did so and add a comment saying what you intended to achieve.

    (This is based on my experiences in coding and in attempting to usefully recomment perl5db.pl).

Re: No Comment
by Nkuvu (Priest) on Apr 23, 2003 at 17:12 UTC

    Hello, my name is Nkuvu, and I'm addicted to comments...

    I'm a prolific commenter, particularly in Perl. But I also know that I have to maintain the comments (usually) more often than the code itself. And it should also be noted that the people who are reviewing my code aren't Perl proficient. So I comment Perl-specific operations, to help the reviewer see what I am doing -- why is usually obvious (but documented if not). For example, if I have ($foo) = $bar =~ s!\\!/!g; I'll comment on it. Because you don't see things like this in C/C++.

    It was also hammered into me throughout my university career that comments are good, lack of comments is bad. Period, no flexibility in that conclusion. But I can see all of the points that other monks have made, and resolve to comment less in the future. Most of my code is very similar to C/C++, due to the people I'm working with. And I can't assume that the person who maintains my code will be a Perl programmer.

    When I started with Perl, it was to update a script written by a no-longer-present programmer. He had very poor style, with variable names like $l (that's an ell) and $x throughout the script. I could have killed for comments in his code, especially since I didn't know Perl. So I've kind of overcompensated since then.

    I suppose I shouldn't admit that one of my scripts (which has a complicated algorithm) is over 50% comments...

      It sounds like you think comments are there to benefit people who are new to programming, or at least new to Perl. The problem is that these types of comments are incredibly distracting once you actually know the language, and at that point they just take up valuable screen real estate that could be filled with code. In most development situations, you should assume that the next person to read the code will be reasonably competent. If not, they have bigger problems than just dealing with your program

        To tell the truth, I never really considered why I should add comments. It was just drilled into my head that I should.

        And once I start thinking about why I should comment things, I can see that I've been going about it all wrong.

        I disagree - I comment heavily on what I was thinking at the time. It has little to do with the actual code, and more to do with intentions:
        # we know this is coming from XXX because of sub xxx, so we don't need + an extra taint check here
        etc. I can go back to code I wrote only a week ago that I've already forgotten (small buffer :) and have trouble going through it quickly unless I do this.

        But then. maybe I'm just dopey :)

        .02

        cLive ;-)

Re: No Comment
by halley (Prior) on Apr 23, 2003 at 17:40 UTC

    Yes, it's particularly difficult recovering from the situation where you were handed poorly-commented code. "Recovering" is about all you can do, retroactively. The solution is in working proactively when you get the chance to mold the minds of your successors.

    I try to instill the following principle in new developers:

    Put strategy in comments, tactics in code.

    Another way to phrase this, though I think it's less strong, is "Comment why, code how." Comments should be an orientation to the general approach, not a roadmap to the use of the language and techniques used. Comments are for the maintenance programmer, who really doesn't want to STUDY your code, just surgically adjust it.

    Enforcing the strategy/tactics metaphor also implies that you have to have a strategy before you can employ effective tactics. For a largish subroutine, start by coding the stub, with an English explanation of the approach to be taken. Under each line of comment, execute the tactics that will meet the strategy. Under "# Arrange unique entries", write the hash scanning and schwartian transform that achieves this aim.

    Lastly, try to phrase your code so that it reads. One trick is to imagine trying to read your code aloud over the phone to someone else. Don't worry about using a few extra lines instead of a few extra clever operators. Don't hide the key conditionals that will control the routine. Be clear.

    --
    [ e d @ h a l l e y . c c ]

Re: No Comment
by dws (Chancellor) on Apr 23, 2003 at 17:44 UTC
    How much trust should you have in comments?

    Over the course of 25 years slinging code, my answer is "less and less." I've been burned too many times by elaborate commentary that had little relation to the "truth" of what the system was really doing. Commentary rarely survives program growth and maintenance.

    The commentary I tend to trust are "what does this do?" comments, if they're brief. The larger the comment, the less I tend to trust it. I also pay a lot of attention to "BUG", "FIXME", and "TBD" comments, though conceptually these are more like Post-It markers in the code.

    POD is really something different. It's external documentation that's been entwined in the code.

Re: No Comment
by Steve_p (Priest) on Apr 23, 2003 at 17:50 UTC
    I believe that most comments are like the old Ronald Reagan quote regarding nuclear disarmament, "Trust, but verify". I myself use comments generally to get my self up to speed a bit quicker regarding some method or a chuck of code, but I do not trust them to be up to date, or even marginally accurate.
      Hear hear! My trust in the comments depends on who wrote the code. I know programmers who cannot be trusted with snake control in Ireland who are also prolific commenters. This should be no surprise; it seems thatthe less people know, the more they talk to prove they know something. (Of course, they usually prove the opposite ...)

      --
      tbone1
      Ain't enough 'O's in 'stoopid' to describe that guy.
      - Dave "the King" Wilson

Re: No Comment
by gmpassos (Priest) on Apr 24, 2003 at 07:41 UTC
    Well, comments... I know that is good to use them to explain the code, but I don't like them, since I think that the programer need to be able to read and understand a code to be a programer.

    The only text that I like to make is the POD for the module, explain how to use. But explain why I made some XS like that, etc... not. Is always better read all the code and understand it, and I never read the comments, they are alway bad, or is easier to understand the code.

    The best comment that you can make are names that make sence for variables and functions/methods (sub). And of course, use a structure/flux for your code that make sence too.

    Graciliano M. P.
    "The creativity is the expression of the liberty".

Re: No Comment
by adrianh (Chancellor) on Apr 26, 2003 at 15:24 UTC

    I tend not to trust comments. I much prefer good unit tests, assertions, well factored code, preconditions, postconditions, etc. "Executable comments" have the huge advantage that they cannot get out of sync with the code.

    One of the many things that intrigue me about perl6 is that things like .wrap, POST, PRE, typing, etc. make this sort of documentation-in-code far easier.

    Favourite comment of all time, which once lived in the guts of a large system I worked on for a few years, was :

    ;;; I don't understand why this works?

    Since the customers had access to the source this was removed at the request of some management when it was noticed. The code it sat above wasn't refactored tho' :-)

    You might also find Documenting Methods/Subs of interest.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://252535]
Approved by particle
Front-paged by RMGir
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (10)
As of 2014-04-24 12:29 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (565 votes), past polls