Documentation: POD vs Comments

[ravenclaw]

I was having a hard time understanding how to use POD documentation when I was habitually using block comments for all my documentation purposes. After reading the Perl Programming Documentation about POD, I found that, where I usually used comment blocks to describe functions, POD is just as effective if not more so. I then wondered, what is the purpose of commenting when POD exists (besides TMTOWTDI). I then realized that I should document my functions using POD and make small notes about the actual code using comments.

For example:

=pod

=head2 mySubroutine

 Takes no argument.  This is a sample
 example to show my idea about documentation
 using both comments and POD.

=cut

sub mySubroutine {
    print 'This is a sample subroutine.', "\n";
    # prints this text because it's a simple example.
}

mySubroutine();

I hope this helps anyone who is just discovered POD and is either now confused about the purpose of both comments and POD or is looking for another method of documenting their code. If anyone has any comments (ha, comments), suggestions, or corrections for this node, please let me know!

Disclaimer:
This is what works for me, and, as always, TMTOWTDI.

[BrowserUk]

The simplest delineation between POD and comments is that POD must (still) make sense without sight of any associated code. Ie. Once it has been extracted and formatted.

Comments on the other hand are semantic extensions of the code with which they are associated and should (must) only be read in that closed context. In most cases they will make little or no sense outside of that context. Comments should enhance the code, not replicate it.

The biggest and most frequent mistake people make is to try and make their comments read as English (or some other language) and so duplicate the code. They do themselves and their readers a disservice by doing so. When the two do not tally, which should the reader take to be the author's true intent?

[toolic]

The Perl Best Practices book dedicates a chapter to the "POD vs. comments" topic.

[JavaFan]

Hmmm, manual pages have existed for many decades, yet C programmers still comment their code.

POD and comments have totally different audiences: POD is to generate manual pages from - the audience is the user of the code. Comments are there for the programmer - the audience is the person maintaining the code.

Not being aware of the difference makes bad documentation. For the user, or the maintainer, and very likely for both.

[tye]

One of the biggest differences between POD and comments for me is that comments don't look like code while POD is not easily visually distinguished.

One of the nice things about POD is how easily and naturally you can include sample code in your POD. So I find it very likely that sample code will get included in POD. And trying to read the actually code when it is shuffled together with POD that includes sample code actually feels like a nightmare &emdash; like I'm just going along opening this innocent-looking file of Perl code and suddenly I realize that it is "finals" and I haven't studied and then everybody is laughing at me because I'm also naked, er, I mean, I suddenly realize that I can't even find the code.

Because, instead of the file containing a block of code that I can read or scan or scroll through or search through, the file contains some twisted "scavenger hunt" where I think I've found some code but it is really just text that looks like code. And when I find the code, I have a hard time concentrating on it to understand it because I'm not confident that I really did find it this time.

Because whether "code" is really code or not depends on whether one of the hundreds of '=' characters in the previous 10 pages happens to be in the first column and also whether that closest prior such '=' is followed by 'cut' or any other word.

Comments require that the fairly distinctive '#' be present on every line. POD actually requires that the ubiquitous '=' character be separated from what you are looking at by at least one blank line.

But even without embedded sample code in your interleaved POD, I find that the POD can greatly interfere with the reading of code, especially for some types of reading (especially less linear types). So please don't interleave POD and code.

Yes, I understand the theory of "keep the documentation close to the code so that when somebody changes the code they'll also change the documentation". But I don't believe it actually works that well. The documentation gets updated most when the documentation gets used. So I think you get better results by concentrating on writing useful documentation.

And it is easier to make documentation useful when you can structure the documentation usefully, not be constrained to a structure that makes sense when shuffled together with your code.

So use comments to explain things that somebody trying to read the code needs to understand. Use POD to write documentation to be used by people who are trying to make use of your code. Quite different audiences who want quite different information. And keep the POD away from the code (such as after the __END__ marker or in a separate *.pod file).

[LanX]

> Because whether "code" is really code or not depends on whether one of the hundreds of '=' characters in the previous 10 pages happens to be in the first column and also whether that closest prior such '=' is followed by 'cut' or any other word.

As a side note, IIRC you don't use syntax highlighting.

[JavaFan]

"use syntax highlighting" is really a poor defense. I'd say that code that isn't readable without syntax highlighting is just that: unreadable. One doesn't always have the luxury of using the editor that's tuned to your preferences - you may be looking at someone elses screen. Or you're debugging some code on a box that only has vi. (And when I mean vi, I mean vi. Not some vi clone renamed to vi). Or you may be reading code outside an editor (more, git blame, ...). Some people don't even have the luxury of easily distinguishing between colours - or they need the black-on-white constrast; any other colour just won't do.

I always write my code assuming the next person looking at the code uses ed and a 80x24 glass monitor, knows my address, and is a sociopath who keeps his axes sharp.

[tye]

Do you use syntax highlighting... in your diff tool? In your merge tool / conflict resolver? In your grep tool? In your print-outs? In your code reviews? In your e-mail? In your 'blame' tool? In your repo browser? etc.

And how do you manage to understand the example code in the POD if the colors aren't right?

Of course, even when you are in a context where you can have your color hints crutch, POD still gets in the way of reading code.

As a side note, IIRC, you use emacs.

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

[JavaFan]

Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.

That's quite subjective. If *I* were the maintainer, you wouldn't score any brownie points.

But, as you said, POD isn't there for the maintainer - it's there for the user. POD doesn't have any way of modifying the order in which it appears in the source file. While there are some cases where you may present the documentation in the same order as the corresponding code appears in the source file, IMO, more often than not, that's not in the benefit of the user. My POD often contains sections that aren't directly related to any specific code (usually, only parts of the DESCRIPTION describe code), and those that do, I usually want to present them to the user in a different order. I may want to describe often used or general functions/methods before less often used, or specialist functions/methods. And sometimes I want to describe my methods in alphabetical order.

Interleaving POD with code means that the flow of your manual page depends on how the code was written. This is a case of "implementation shining through". Which I think is a thing that should be avoided.

[tye]

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.

Excellent points.

Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.

Much (in a great way) like (similar to) a (singular article) sentence (grouping of words expressing an idea) doesn't (fails to) make (produce) sense (coherent meaning) without (lacking) the (definite article) definition (explanation of meaning) of (preposition) words (grouping of lettings expressing a concept).

Make your reader's life easy by keeping the word definitions as close as possible to the words! It would be crazy to have a separate document that explains the basics and then to expect your copy editor to actually understand the meaning of English words before she jumps in trying to edit your sentences.

Oh, some of my definitions above rather suck. I find that often happens when I'm forced to shift tasks in the middle of composing a sentence and throw together a word definition in order to get the boilerplate in place so I can type in the next word.

[Anonymous Monk]

Much (in a great way) like (similar to) a (singular article) sentence (grouping of words expressing an idea) doesn't (fails to) make (produce) sense (coherent meaning) without (lacking) the (definite article) definition (explanation of meaning) of (preposition) words (grouping of lettings expressing a concept).

Make your reader's life easy by keeping the word definitions as close as possible to the words! It would be crazy to have a separate document that explains the basics and then to expect your copy editor to actually understand the meaning of English words before she jumps in trying to edit your sentences.

Oh, some of my definitions above rather suck. I find that often happens when I'm forced to shift tasks in the middle of composing a sentence and throw together a word definition in order to get the boilerplate in place so I can type in the next word

Touchy (french for bullseye)!

The difference is it isn't like english prose, its more like dictionary

=head2 C<< Much  >>

a definition

=cut

sub Much  {
    "in a great way";
}




=head2 C<<  like  >>

a definition

=cut

sub  like  {
    "similar to";
}




=head2 C<<  a  >>

a definition

=cut

sub  a  {
    "singular article";
}




=head2 C<<  sentence  >>

a definition

=cut

sub  sentence  {
    "grouping of words expressing an idea";
}




=head2 C<<  doesn't  >>

a definition

=cut

sub  doesn't  {
    "fails to";
}




=head2 C<<  make  >>

a definition

=cut

sub  make  {
    "produce";
}




=head2 C<<  sense  >>

a definition

=cut

sub  sense  {
    "coherent meaning";
}




=head2 C<<  without  >>

a definition

=cut

sub  without  {
    "lacking";
}




=head2 C<<  the  >>

a definition

=cut

sub  the  {
    "definite article";
}




=head2 C<<  definition  >>

a definition

=cut

sub  definition  {
    "explanation of meaning";
}




=head2 C<<  of  >>

a definition

=cut

sub  of  {
    "preposition";
}




=head2 C<<  words  >>

a definition

=cut

sub  words  {
    "grouping of lettings expressing a concept";
}

[Anonymous Monk]

"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." -- DrHyde.

Your "good" & "bad" situations are reverse for me. Please offer that as your personal preference but not as some kind of truth.

[Anonymous Monk]

Your "good" & "bad" situations are reverse for me. Please offer that as your personal preference but not as some kind of truth.

Why? It is the truth according to DrHyde -- what theory of truth are you operating under?