NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.
All the Perl that's Practical to Extract and Report
several minutes ago. We don't need no stinkin' tactical nukes.
(By the way, do you have change for 10 million people?) --lwall
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.
Re: Vim: Folding POD Out Of the Way (Score:1)
"Almost all of my modules are written with inline POD because I believe it's very important for the documentation to be next to the code, but if you've worked on a codebase for any length of time, that POD quickly becomes annoying".
You like to have the Pod by the code but it is annoying. So this fixes it for you by making it not annoying.
What about the next person who reads your code and doesn't have a Vim Pod folding macro. They are going to find it annoying, right?
Inline Pod *is* annoying. It make code di
Re: (Score:2)
Putting the documentation near the code is no guarantee that it will get updated when the code does.
Agreed, but putting documentation after the __END__ is pretty much a guarantee that it will not get updated when the code does. (That's been my experience; your mileage may vary.)
Re: (Score:1)
Either way it comes down to the diligence of the maintenance programmer so I don't see the advantage.
What I do see is the disadvantage. The blocks of Pod that you say "quickly becomes annoying".
If you step back from this don't you get one of those smells that you like to look out for. What it looks like to me is that a method of documenting a module is "annoying" and that the solution is to change the behaviour of the tool for viewing the code. That doesn't look like a good solution to me since it only work
Re: Vim: Folding POD Out Of the Way (Score:2)
I can see that point. I guess the reason I switched to inline POD is because it makes writing documentation very easy for me. Of course, folding the POD also becomes useful when I'm working on someone else's code. I can't dictate to them how to write their POD, so I work around that.
Reply to This
Parent