I find there is no good solution for all cases.

I want the POD to read as a coherent document, which is hard to ensure if it is broken up across the code. The ideal ordering of the methods/functions in the code is not always the same as the ideal ordering within the documentation.

On the other hand, my experience is that if the documentation is not next to the code, people are much less likely to read the documentation when looking at the code (resulting in them reading the code with incorrect assumptions about the intent), and much less likely to update the documentation when changing the code.

I guess I put them inline 90% of the time, the remaining cases are those where that would make it too hard to maintain the desired structure.

Hugo

The ideal ordering of the methods/functions in the code is not always the same as the ideal ordering within the documentation.

This! You may want to group the functions together in one way in the module, but prefer to structure the POD in a different way. This approach is easy when the POD's contained in a separate file from the code.

.. my experience is that if the documentation is not next to the code, people are much less likely to read the documentation when looking at the code ..

Mmm, that's a matter of opinion. The POD should contain enough information for someone using the module to write code that uses it. If they also have to look at the code, that's a problem with the POD. I can think of a number of modules that I've used where I've never looked at the code, but have re-read the POD lots of times.

.. and much less likely to update the documentation when changing the code.

It would be poor software craftsmanship to update the code without updating the POD. I would expect a PR that improves/alters the code for a module would include code, documentation, and some information about what the goal of the change is. And in the Perl world, backwards compatibility is really, really important.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

.. my experience is that if the documentation is not next to the code, people are much less likely to read the documentation when looking at the code ..

Mmm, that's a matter of opinion. The POD should contain enough information for someone using the module to write code that uses it. If they also have to look at the code, that's a problem with the POD.

Hmm, I'm not sure I agree that my experience is a matter of opinion. :)

If someone comes to read the docs, I would usually expect that they'll use perldoc or similar. This is about people coming to look at the code.

A typical workplace example is that a developer picks up a bug report, analyses it to the point they see a method call somewhere clearly expecting some behaviour, and sees in the method that it does not implement that behaviour. They then make an assumption (effectively a guess) about whether it's the call or the implementation that is wrong, rather than determining that from the documentation of the method. Having the documentation right there when they look at the implementation is one small way to help them avoid that error.

It would be poor software craftsmanship to update the code without updating the POD.

Yes. Sadly, some human software developers are not perfect. We should do what we can to help them overcome their imperfections - to make it as easy as possible to do things right. Having docs next to the code it describes is one small way to make it easier to do things right.

The POD should contain enough information for someone using the module to write code that uses it

But this module currently only has me using it. As I said in the question, it is a utility module that will never be published. The reason I am adding POD is to help me remember what what all the methods do without having to keep diving into the source code to look at comments and inspect the code.

We will almost certainly bring on another developer at some point. But even then, I don't expect this module will ever have the same level of POD detail as I would apply to a module that was destined for CPAN.

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.

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

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.

am I opening myself up to future problems if I spread the POD through the module and document each method next to that method's code?

No, you are not. The placement of the POD is mostly a micro-optimisation and can therefore be ignored in most cases. The all-the-POD-at-the-end rule of thumb is only really relevant when preceded by an __END__ so that the interpreter stops processing the file at that point. I guess that's the very strictly correct way to do things but the benefits for a module without MegaBytes of POD are so slight that it's pretty much irrelevant.

Unless/until you are writing a module which is used almost everywhere, the POD placement really isn't worth worrying about IMHO.

For my code, i usually order it this way:

1. hashbang or package name
2. global use statements that are common to all pm files ("autopragmas" that can get updated by a script)
3. local use statements
4. package constants/variables
5. new() function
6. all "main"/high level functions
7. helper functions
8. __DATA__
9. __END__
10. POD

Basically, the more "important" higher level stuff goes first, the lower level stuff goes lower, the optional stuff comes last. Makes it slightly more inconvenient to updates documentation, if i add one at all; a lot of my internal, for most of my personal use stuff i don't even bother. But when debugging/changing/enhancing a perl module, i look for the high level stuff first and only go into internal helpers later, if at all.

For debugging (no matter if it's my code or someone else's), a lot of the times the POD is either useless are plain wrong. You know, it either describes the behaviour that the code should exhibit but doesn't, or the POD is outdated. So that's the part of a file i rarely look at, therefore it goes at the bottom. And unless i want to actively change the POD, i nearly always look at the documentation generated from the POD (man pages, metacpan), not the POD itself.

But that's just how i handle POD. There is no "best" way. If you are unsure, just try a few different ways and see what you like best.

Because the module is never really 'finished' and gets added to whenever I need a new method, it seems sensible to add the POD next to each method

Despite you being the module implementor and its only user, I still feel it's good discipline to maintain a clean separation between interface and implementation (for example, by placing the module's external user-interface POD after the __END__ token in the .pm file, while inserting technical implementation comments right next to the code they are clarifying).

Hopefully doing that will help improve code quality, while making it a snap to release your handy utility module to a wider audience in the future.

See also: Commenting and Documentation References

Updated: minor changes to wording.

👁️🍾👍🦟

Despite you being the module implementor and its only user, I still feel it's good discipline to maintain a clean separation between interface and implementation

Whilst I am the module implementor and only user, one or two other people will probably be involved in using and developing this module in the future. However, it will never be a public module as its functionality is useless outside the ecosystem for which it was created.

Normally, I do add POD at the end of a module, as you suggest.

The question comes about here because the module is updated very frequently and evolves to meet changing needs in the rest of the codebase. This seems, on the surface at least, to warrant having the POD for each method next to that method.

Having read the various comments, I shall try interleaving POD with code. It is not exactly going to be hard to group it all together and relocate it to the end of the file if I find issues with this approach...

For classes/roles/utility packages, I will normally include pod at the end of the pm file. It just seems neater to have it all together, and the most logical order for methods to be documented in isn't always the same as the most logical order for them to be programmed in.

As an exception, for a handful of projects parts of the code, tests, and/or documentation are auto-generated based on templates, and in those cases I'll often want to generate the documentation, code, and tests in separate files for convenience.

Some documentation is more overarching and tutorial-like in nature, so lives in separate pod files.

My preference is to have all of the code functions together -- that is, not alternating with POD. POD lives in a separate file, since that's one of the options.

I am known as a developer who includes lengthy comments, so there is documentation in my code. I just prefer to keep user information somewhere else -- that's not useful information for me, so I don't want to see it. And I'm aware that some IDEs allow you to hide POD -- that's wonderful, but I'll stick with plain vanilla vim. It's always available, and behaves consistently pretty much anywhere.

POD lives in a separate file

Thanks. I hadn't considered that a separate file would be a default choice but your explanation makes sense. Although, I don't think I'll be following your lead for my private module. I might move in that direction for CPAN modules perhaps.

I'm very much looking forward to discovering what other people do and why they do it...

Because my editor/IDE allows me to fold subs, I don't like to intersperse POD, so the vast majority of time, I put my POD at the end of the file. I like code and docs separate.

Sometimes I create separate POD files entirely, but very rarely.

For finding sections of my code, I use a heading, via comments, but one that is large and easy to see when scrolling quickly past it. This can be as simple as something like this for a function...

# -------------------------------------------------------------
#   P R O C E S S    R E P L A C E M E N T S
# -------------------------------------------------------------
[download]

<!--
#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^
# ******* S T A R T   O F   J A V A S C R I P T S   H E R E ! ! ! ****
+***
#_____________________________________________________________________
+____
-->
[download]

<!--
#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# ******* N E W   A C C O U N T   C R E A T I O N *******
#________________________________________________________

  -----                                                               
+-----
1 | H |                                                               
+|He |
  |---+----                                       --------------------
++---|
2 |Li |Be |                                       | B | C | N | O | F 
+|Ne |
  |---+---|                                       |---+---+---+---+---
++---|
3 |Na |Mg |3B  4B  5B  6B  7B |    8B     |1B  2B |Al |Si | P | S |Cl 
+|Ar |
  |---+---+---------------------------------------+---+---+---+---+---
++---|
4 | K |Ca |Sc |Ti | V |Cr |Mn |Fe |Co |Ni |Cu |Zn |Ga |Ge |As |Se |Br 
+|Kr |
  |---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
5 |Rb |Sr | Y |Zr |Nb |Mo |Tc |Ru |Rh |Pd |Ag |Cd |In |Sn |Sb |Te | I 
+|Xe |
  |---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
6 |Cs |Ba |LAN|Hf |Ta | W |Re |Os |Ir |Pt |Au |Hg |Tl |Pb |Bi |Po |At 
+|Rn |
  |---+---+---+-------------------------------------------------------
+-----
7 |Fr |Ra |ACT|
  -------------
              --------------------------------------------------------
+-----
   Lanthanide |La |Ce |Pr |Nd |Pm |Sm |Eu |Gd |Tb |Dy |Ho |Er |Tm |Yb 
+|Lu |
              |---+---+---+---+---+---+---+---+---+---+---+---+---+---
++---|
   Actinide   |Ac |Th |Pa | U |Np |Pu |Am |Cm |Bk |Cf |Es |Fm |Md |No 
+|Lw |
              --------------------------------------------------------
+-----


-->
[download]

Sometimes my header can be removed once active development on that section is complete. It just helps me find it at the time I am working with that section.

These headers have been my way of navigating my code more easily, as each of the 20+ files in the required codebase has over 1,000 lines on average.

I have a related question. Is writing POD necessary when one is publishing a module or is it optional? What if the author's preferred way of writing documentation is HTML format instead of POD? What if he wants to publish the documentation alongside the module in PDF book format?

Is writing POD necessary when one is publishing a module or is it optional?

It is both necessary and optional!

It is perfectly possible to publish a module to CPAN with no POD at all. CPAN allows this.

But if users have no idea how to use a module, they won't use it... If users are not going to use it, why bother publishing it? So, treat POD as mandatory for all modules you are going to publish. Would you use a module if you were given no clue about what it does or how you make it do anything?

You need some POD. The online documentation that you see on CPAN is harvested from the POD embedded within the module. I'm not experienced enough to know how to publish that portion via strictly HTML or some other format. A PDF would be useful for a larger or more complicated explanation, but there is nothing stopping one from linking to a PDF within the POD. POD has its own styles for markup, but HTML can be used within POD if specified.

One may get an idea of how a module will be shown on CPAN via this POD renderer:

https://metacpan.org/pod2html

I found it to be close, but not perfect; in my case requiring some later adjustments to manipulate the final formatting of the displayed POD.

The formatting codes, including illustrations for how to embed HTML, are available here:

https://perldoc.perl.org/perlpod

Blessings,

~Polyglot~

Hi, I suggest to ask in a separate thread your related but separate question.



The way forward always starts with a minimal test.