Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

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

by BrowserUk (Pope)
on Sep 12, 2003 at 19:56 UTC ( #291170=note: print w/ replies, xml ) Need Help??


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

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.


Comment on Re: Re: Reasons for looking at your favourite module's source
Download Code
Re: Re: Re: Reasons for looking at your favourite module's source
by tachyon (Chancellor) on Sep 13, 2003 at 10:47 UTC

    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://291170]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (8)
As of 2014-12-27 22:00 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

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





    Results (177 votes), past polls