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

Re: Perl code - sometimes UGLY...

by perrin (Chancellor)
on Apr 29, 2009 at 05:23 UTC ( #760812=note: print w/replies, xml ) Need Help??


in reply to Perl code - sometimes UGLY...

I tend to agree about interleaved POD being hard to read. I much prefer it in one chunk at the end of the file.

Replies are listed 'Best First'.
Re^2: Perl code - sometimes UGLY...
by pemungkah (Priest) on Apr 30, 2009 at 19:17 UTC
    I think it depends on the code in question. The debugger docs are interspersed, and they make it somewhat possible to understand what in heaven's name is going on. If they'd all been in a lump at the end they'd be almost useless.
      Nope, it doesn't depend on the code. Interleaved POD is always wrong. Phew, glad I got that off my chest!
        Glad to give you a chance. Can't keep that stuff bottled up - it's bad for you. :)

      Just wanted to put in that I agree with you. My system is that programs are documented at the end, and libraries are interleaved.

      The difference being to me that programs are designed to be used and understood by non-programmers, so the docs often have little or nothing to do with any specific code. Libraries on the other hand are designed to be used by programmers, and each function should be documented on what it does (or, at least, what it is documented to do...) anyway, so the interleaved docs can often serve both purposes: Telling users how to use functions/methods, and telling maintainers what those functions/methods are intended to do.

      Otherwise I'd have to write both a comment and documentation, and they'd have to both be maintained in parallel. Interleaving them I only have two things to maintain: the docs and the code.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (5)
As of 2019-12-08 16:59 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?