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

Re: Documentation: POD vs Comments

by BrowserUk (Pope)
on Jul 21, 2011 at 18:57 UTC ( #915965=note: print w/ replies, xml ) Need Help??


in reply to Documentation: POD vs Comments

The simplest delineation between POD and comments is that POD must (still) make sense without sight of any associated code. Ie. Once it has been extracted and formatted.

Comments on the other hand are semantic extensions of the code with which they are associated and should (must) only be read in that closed context. In most cases they will make little or no sense outside of that context. Comments should enhance the code, not replicate it.

The biggest and most frequent mistake people make is to try and make their comments read as English (or some other language) and so duplicate the code. They do themselves and their readers a disservice by doing so. When the two do not tally, which should the reader take to be the author's true intent?


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.


Comment on Re: Documentation: POD vs Comments

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (5)
As of 2014-04-19 19:20 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (483 votes), past polls