Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

Re: Reasons for looking at your favourite module's source

by jdtoronto (Prior)
on Sep 12, 2003 at 14:21 UTC ( #291055=note: print w/ replies, xml ) Need Help??


in reply to Reasons for looking at your favourite module's source

I especially liked the comment about going back to your own code 5 years on. Back in the late 60's I started working in Fortran-IV. This same code is the root of a product which has been through many incarnations in a variety of languages over more than 30 years. Incarnation TWO was a problem, there were no comments in incarnation ONE so I had to go back and work it all out by hand. But since then, each change or addition in whatever language has been thoroughly documented, to the point where the comments are now about 1.5 times the size of the code itself and they provide a wonderful insight into over thirty years of development.

A simple rule:

If you comment well, no amount of comment is too much

And yes, there are Perl coders out here who have been at it that long!

jdtoronto


Comment on Re: Reasons for looking at your favourite module's source
Re: Re: Reasons for looking at your favourite module's source
by BrowserUk (Pope) on Sep 12, 2003 at 19:56 UTC

    It's strange, but no matter how many times I see the arguments for "lots of comments", no matter how well argued they are, nor matter whether the proponents are those I have great respect for or not, I always end up with the same thought running through my brain.

    If I cannot understand the code without reading the comments, then I need to work out how that code works, for myself, without hints, otherwise I won't really understand it, and therefore risk breaking it when the time comes to modify it. This is true whether then code in question is old code of my own, or code I get from someone else.

    For me, this is a little like driving a car without having an appreciation of what goes on under the bonnet (or in the EMU or ABS etc.). Many people are quite happy to be oblivious to the details, and are quite comfortable with just knowing that the feature is there and working on their behalf, but I just have to know how it works.

    I realise that this is indicative of (another) character flaw in myself, rather than a condemnation of others, but that's just how I am.

    That's why I tend to stick to the occasional comment in my code of the form "This next bit does such and such", rather than copious explanations of every routine or block. These act as flags that draw my attention to those bits of the code that will probably require some effort on my part to understand again in 2 years time. As such, they serve a higher purpose than just explaining the code, they draw attention to those bit that need explanation.

    My tendancy to remove overly copious comments from other peoples code and read the code rather than the comments comes from several, painful examples where the comments were innaccurate, out of date, or just plain wrong that caused me personal and/ or profesional grief.

    I had one person say that "Of course you shouldn't believe the comments verbatim, you should always check that the code does what the comment say!".

    My only response to that is: In that case, what damn purpose do the comments serve?

    This is a very personal viewpoint, and not one I expect many people to share, but until someone devises a mechanism for testing the comments along with the code, I will continue to believe only what the code tells me, and will, at best, ignore the comments, but if they are too copious

    ####################################################### # # # OOO RRRR L OOO U U DDDD # # O O R R L O O U U D D # # O O R R L O O U U D D # # O O RRRR L O O U U D D # # O O R R L O O U U D D # # O O R R L O O U U D D # # OOO R R LLLLL OOO UUU DDDD # # # #######################################################

    and therefore distract from my overview of the structure of, and close-up view of the detail of, the important stuff, IE the code, then I will delete them.

    My editor macro for doing this in perl code is beginning to get quite clever:)


    Examine what is said, not who speaks.
    "Efficiency is intelligent laziness." -David Dunham
    "When I'm working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong." -Richard Buckminster Fuller
    If I understand your problem, I can solve it! Of course, the same can be said for you.

      Let the code describe what is being done and comments simply to describe why.....

      # the sort on length means we will delete # dir/subdir/subdir/ before dir/subdir/ and dir/ # which avoids a directory not empty error for my $dir ( sort { length $b <=> length $a } @$dirs ) { rmdir "$DOC_DIR/$cwd/$dir" or $errors .= "Failed to delete $cw +d/$dir: $! "; }

      cheers

      tachyon

      s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (7)
As of 2014-12-21 21:16 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (108 votes), past polls