Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

comment on

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

At the very minimum, documentation should be moved to the bottom of the source file. Interleaving it with the code, detracts from the code in ways that go far beyond just interrupting the programmers overview of the code.

You're in agreement with Damien Conway on this, but myself I think interspersed pod-style has some strong DRY advantages. Most subs require some verbal description to go with them, and there's some overlap between what you need to say for the benefit of a maintenance programmer working on your code and a client programmer interested in using your code, and it's not at all a bad idea to put that inside an "=item" that goes with the sub. (And I would hope that it is obvious that remarks that are only of interest to a maintenence programmer should be confined to comments.)

It also creates dependencies.

The dependencies between the documentation and the code do not go away if you move the documentation elsewhere.

Personally, I think that POD has it backward. If you want to go with the idea of containing code and documentation within the same file, I much prefer the Literate Programming concept of having the interpreter/compiler simply ignore everything outside of some equivalent of , blocks, as is used by Haskell, D and others. This allows you to write the documentation first, in whatever markup it adopted by the project, and using the full power of that chosen markup.

I'm once again, having trouble figuring out what you're getting at here. Nothing about the interspersed pod style I'm arguing for prevents you from writing the documentation first, and in fact I often work that way. Of course, if you use this style you have to present the code in the same order that you want it to appear in the documentation, and that's a problem that would go away in a true "literate programming" language.

By the way: you do understand that you can embed other markup inside of pod if you want to, right? From perlpod:

=begin html <hr> <img src="thang.png"> <p> This is a raw HTML paragraph </p> =end html

If you must keep it in the same source file, at least keep it all together. Preferably at bottom after the __END__ mark, though that is impossible if the code uses a __DATA__ section.

Actually, you should get out of the habit of using __END__ at all: it breaks mod_perl code.

In reply to Re^3: Programming *is* much more than "just writing code". by doom
in thread Programming *is* much more than "just writing code". by BrowserUk

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!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • 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
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            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?

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

    How do I use this? | Other CB clients
    Other Users?
    Others browsing the Monastery: (3)
    As of 2021-04-23 01:38 GMT
    Find Nodes?
      Voting Booth?

      No recent polls found