Separation of Concerns
In the world of Perl programming, nothing annoys me more than opening up a module and finding a bunch of POD interleaved with code. I've heard people argue in favor of this atrocious practice, saying that it allows the documentation for a function to be next to its implementation. But if I'm reading the code at all, it's only because I've already read the documentation and it wasn't good enough. That's not meant to be an insult -- maybe I was trying something weird that the author didn't intend, or trying to track down a bug that the author was not aware of.
The purpose of documentation is to describe the public interface of your module. Ideally, your module is perfect, and nobody should ever have to look under the hood, because all anyone could ever need is the publicly provided interface. But of course, no module is perfect; there are bugs, there are desired features that aren't there. There are functions that work fine but execute in exponential time under one circumstance that nobody thought of.
If someone's looking at your code, it's because they need more information than the documentation or interface itself can provide. Interrupting the flow of code with chunks of POD makes it that much harder to follow what's going on. If you're looking at your own code, you almost certainly don't need the POD there in front of you, but if you do, maybe your interface is too complicated.
Also, does anyone know of an Emacs thingy that will hide POD upon the mashing of a magical sequence of keys?
</rant>
Mike Friedman is a professional computer programmer living and working in the New York City area.
The magic keyword you’re looking for is “folding”, which is a general term for an editor feature which lets you roll up a sequence of lines into a placeholder line that you can open or close.
I don’t know how to do this in Emacs, though.
(Oh, and I agree that interleaving POD is an awful style.)
Hell yes!
I really really hate it!
your all crazy,
also, use you're googler:
http://www.perlmonks.org/?node_id=463336
further, if it weren't interleaved, you wouldn't be able to fix the documentation while you were viewing its imperfection. and that's what you intended, right?
Why not? If you can use folding to get inline POD out of sight, you can certainly equally well use split windows/buffers to keep out-of-line POD in sight.
But writing documentation and changing the code are often tasks with different breakdowns; further, maintaining coherency in both often requires sweeping changes rather than localised pecking. Inline POD just makes such work unnecessarily difficult.
I also do not like inline POD. That is why I use the PBP extension to Module::Starter (would be nice if it was an option somehow from M::S itself).
This is something Emacs (Lisp) gets right. Function documentation should be next to the function, but it doesn't count as a manual. Write both.
Robert: I don't know what PBP is, but if you send a patch to cjac@colliertech.org, I'll review it and get it in if it passes muster.
http://code.google.com/p/module-starter/
I have to agree that inline pod is awful. I wish people would stop doing that.
What "code flow" is being interrupted by the pod? I have yet to see a chunk of pod in the middle of a block.
I have the opposite rant: I hate having a big chunk of pod at the beginning/end of a file. I'm not a huge fan of having it all in a separate .pod file either.
I find that I write better documentation if the pod for the method is right above it. If you've separated the pod into another chunk/file, how do you easily verify that a method is documented or track down its documentation?
These are questions for the author/maintainer and not for the user. Though I'll grant that users might need to read the code for cases where the documentation is lacking. At which point, the question becomes: which way gets you more/better documentation patches?