Slash Boxes
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

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • "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

    • 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.)

      • 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