in reply to Where to place POD

Where do you place your POD, and why do you do it that way?

Either interleaved or at the end.

Most often, I interleave, because that helps me remember to update the documentation for a function any time I update the function. Plus it helps me remember the purpose and usage of a function as I'm working on it (comments might help with implementation details, but having the user-perspective documentation right there with it helps me keep the big picture in mind, especially when I'm maintaining a section of code months or years after the last time I needed to touch it).

I would personally never put it in a separate .pod file, as it would be "out of sight, out of mind" in terms of keeping it up to date.

Replies are listed 'Best First'.
Re^2: Where to place POD
by GrandFather (Saint) on Jan 15, 2024 at 08:52 UTC

    Your "interleave" argument is what these days tends to drive me to use a separate file. I pretty much always develop with an IDE using two windows - source on the left, reference (header files, POD, ...) on the right. That way I have the API reference immediately to hand without scrolling or switching tabs - the code and "API" are side by side.

    Optimising for fewest key strokes only makes sense transmitting to Pluto or beyond
[reply]

      Like you, I too use two windows in my IDE, but instead of having POD in a separate file, I just open two windows to the same file. One the code, the other at the bottom of the file where the POD is. I always write POD as I'm writing the function/method, and when making updates to code, I've got the POD handy much like you for both review, and edits.

[reply]

In Section Seekers of Perl Wisdom