Stories
Slash Boxes
Comments
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.
 Full
 Abbreviated
 Hidden
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 difficult to read, especially if it contains code snippets. But you could avoid the annoyance by putting the Pod after the __END__. Then no-one will have to make their editor, or their brain, jump through hoops.

    Putting the documentation near the code is no guarantee that it will get updated when the code does.

    John.

    --

    • 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

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

        • What I do see is the disadvantage. The blocks of Pod that you say "quickly becomes annoying".

          He fixed one big annoyance (documentation far removed from the code such that it doesn't get updated when the code does) which causes another smaller annoyance (lots of small POD blocks scattered in your code).

          Trading big problems for small problems is what we do as programmers. How is this any different?

          And in any case, he's solved the small problem (at least for his tastes, which is all an editor can really do), so why the criticism?