Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

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.


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

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others examining the Monastery: (3)
    As of 2014-09-21 09:51 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (168 votes), past polls