Inline Pod Or Not

In PerlLanguage, even a typical program can be made into an approximation of LiterateProgramming (SelfDocumentingCode) using POD ("Plain Old Documentation": http://www.perldoc.com/perl5.6/pod/perlpod.html) - although POD on its own is not LiterateProgramming (see http://www.perl.com/lpt/a/tchrist/litprog.html).

Here's a POD example. You might type this as "silly.pl":

 #!/usr/bin/perl

 =head1 NAME 
 Silly script 
 =head1 SYNOPSIS

 Prints out "Foo!"

 =cut

 print "Foo!\n";

and, if you run "perldoc silly.pl" you'd get:

 NAME

 Silly script

 SYNOPSIS

 Prints out "Foo!"

whilst running the script would, of course, print out the foo. Now, in a piece of serious Perl (especially if it's getting into the KLOC range, but we won't talk about that now) you're going to have a whole bunch of functions, good Perl style says (http://www.perldoc.com/perl5.8.4/pod/perlmodstyle.html#POD) you should document them, so it's going to be a lot more detailed than this naive example. Of course, if you're using MeaningfulNames, you might not want to document every single one, because then you might get into MassiveFunctionHeaders territory.

But, and here lies the point I've been slowly approaching, much like everything in Perl, TimTowTdi. Some people like to put their blocks of POD inline with the rest of their code, so that a chunk describing a method would sit directly above the method itself. Others, myself included, prefer to put all the POD at the end of the code (after __END__, which nets you some tiny speed gain as well). Both styles produce an identical result when rendered. I prefer the latter because I find inline POD makes the code harder to read, especially when it's someone else's code I'm trying to skim through to get an idea of what's going on, and especially when, as POD commonly does, it contains chunks of example code within it, making me have to stop and scroll up and down to work out whether I'm looking at live, functional code or merely documentation. What do people here prefer when it comes to writing their PerlLanguage?

I prefer to interleave, because it is more likely when changing a function that I will update the documentation. Since inaccurate documentation is worse than useless, I personally consider this to trump all other more aesthetic considerations.

(Note: http://perlmonks.thepen.com/94969.html contains the same question asked by someone else, with longer code examples, which demonstrate the two styles much better.)

---

CategoryPerl. See also: StripExcessiveComments, CommentsAreCode, DocumentationBeyondTheSourceCode