Re: Documentation: POD vs Comments

[DrHyde]

POD is documentation for the *user* of your code. That could be an end-user, or it could be a programmer who is using your code. POD should document what the code does.

Comments are documentation for the *maintainer* of your code. Comments should document how the code does what it does. So for example it documents the algorithm and anything else that might not be immediately clear to a maintainer.

So, for example, in this module the POD simply tells you what methods exist, what arguments they accept, and what they return, and then there are comments like:

  # we override these in the test suite to avoid having to be root
  ...
  sub stat { return CORE::stat(@_); }

but that subroutine isn't even mentioned in the POD. It's not something that a user needs to care about.

Then in the subroutine that does the bulk of the work there are small comments every few lines that explain all the steps in the algorithm:

  # if a user has been specified, first get their UID (from their
  # username if necessary).

  ...

  # now divine the user's permissions.  first get the file's mode
  # bits and ownership

  ...

  # now check user/group perms.  Set isReadable etc if the mode has
  # the owner bit set and the user is the owner, or has the group bit
  # set and the user is in the right group

  ...

  # root can read and write anything, can execute anything
  # with any x bit set

As an aside, I'd note that comments are really only useful in conjunction with the user-level documentation. Maintainers needs to know both what the code is supposed to do and how it does it. Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents. Scattering POD inline with code is Good, putting it all at the beginning or end of the file, separate from what it's documenting, is Bad.