Re^3: Programming *is* much more than "just writing code".

[doom]

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.