The PBP likes documentation in POD, in your source files, but wants it all in one chunk, separated from the code it documents. This is one of the suggestions in the PBP I not only disagree with, I find damaging. I feel strongly that the documentation goes as close to the code as possible, to minimize the distance between them and make the tendency to avoid updating them harder to forget.
The book warns this leads to contorted code or documentation. I have not seen that happen. What I have seen is having to re-arrange code so the documentation made sense. But if the documentation makes sense, the code seems to always make sense in the same order.
The book also says that keeping documentation apart from the code makes it easier to remember to update. It’s a separate step and you have to do deliberately do it, rather than just looking over the thing that’s there. As far as I have seen, that’s claptrap. If it’s not near the code, it doesn’t get updated, and then it’s wronger than it was before.
Everything I have done shows that documentation kept further from the code is harder to maintain – both in the cognitive load of needing to remember to do it, and in the technical aspect of not being able to see as much of the code and documentation as possible together – and less accurate.
I have found this to be a really bad suggestion, and one of the few in the PBP that I find not just wrong but damaging.
FWIW, I completely agree with your POV.
Whereas I go with the book on this one. I hate POD interspersed with the code. I find it makes it harder to both read and write both the code and the POD.
I think this is one of those things where there’s two kinds of people.
I think POD contiguous is better than in between code because it lets you structure the POD more naturally rather than contriving it to have the same structure of the code, e.g. you may want to order things differently in code and in POD, to some degree. Also many sections in POD don’t directly correspond to parts of code, so how do you arrange those mutually. So I think POD should all be together. I would even have the POD in a completely separate file, e.g. you can have Foo.pm and Foo.pod side by side in a distro if you want, and that also gives you the option to split the POD into a different number of files than your source code, so each is arranged more naturally.
I’m another pod/code miscegenator, at least for library code (typically .pm modules). If you’re writing detailed documentation for a bunch of entry points (methods of a class, or functions in a procedural module), I find it most reasonable to put the documentation for each function right above the function, just like some people put a block comment above each function explaining its behavior and expected usage. There will typically be some intro pod sections near the top (synopsis, description, etc.) and some sections at the very end (author, copyright/license, see also, etc.). I find this layout most comfortable and easy to maintain when the bulk of the pod is per-entrypoint.
For an executable (typically a .pl file), my preference isn’t as strong. Sometimes, if there are a number of mutally exclusive options, each implemented in its own block of code, I’ll document each option in a pod block above the implementation. Other times, when the documentation is mostly paragraphs of text explaining what the program does and how to use it, I’ll put all the pod at the end. One advantage of having all the pod in one place is that it’s more obvious if you’ve left something out or repeated part.
A library module which needs a lot of explanation, but whose entrypoints are few and self-explanatory might also be better with the pod at the end.In border-line cases, which way I arrange the pod is a matter of historical accident. If I started by documenting the entrypoints, the pod will probably be intermingled; if I started by writing an explanation of the module as a whole, I might have put the whole thing at the end. So far, I’ve never felt impelled to go back and re-arrange my pod from one form to the other.
I’m an interspersed pod guy, myself, though obviously there may be exceptions (that could be another perl programmer slogan “there are always exceptions”).
I think this debate is one of the symptoms that there are two completely approaches toward thinking about programming. I think in english, and continue to think largely in english even while programming, but there are some programmers who seem to switch over “code-brain”, and they find dealing with english very intrusive.
Myself, I often find myself revising the pod to match the code while I’m reading the code, so interspersed pod seems to work for me, at least.
Some languages have this built-in as a feature, the docstring is part of the function definition.