The problem with POD is that it's darn ugly. I appologize, I don't wish to badmouth it, but it really just is ugly :-)

YES!!! not fifteen minutes ago was i muttering about the ugliness of POD. i'm in the final phase of a project for my current client, and i'm reviewing all the code and making sure the docs are updated as i turn everything over to the admin team. i use CodeWright for my editing, which does wonders to make perl code pleasant to look at, but does nothing to make pod code readable. i haven't taken the time to modify the lexer to color-code POD code, but i think i'll do just that after this job.

but POD is ugly. i place mine at the end while i'm coding, because i hate to look at it. when i'm done with a program, usually i'll move it inline so whoever's maintaining the code is more likely to update the doc. (although i have no proof that putting the POD inline increases the likelyhood of maintenance, i do it anyway.)

i tend to use well named variables and functions, and code comments to document my code. typically, i also generate detailed design documentation. sometimes i use pod to generate this, but lately i've found myself writing the doc and then cut/pasting the text into the script as pod. there, i've said it... pod's so ugly, i use Word instead! ACK. i feel dirty.

~Particle

I've mainly two reasons for that. A theoretical one, and a practical one.

Let's start with a practical one. Ever tried figuring out what a module is exactly doing? Ever tried that with modules that use inline POD? It's like eating soup with loads of hair in it - you can't quickly see what is code and what is POD, especially if the POD uses code blocks! It becomes harder to find the functions.

But the theoretical one is more serious. POD is for writing *user* documentation. That's why pod2man is run. And user documentation describes how you use a program, or a function. Not how it's implemented, unless that's relevant to the usuage. Regardless whether it's a module or a standalone function. Look at your systems manual pages, be them from section 1, 2 or 3. They talk about usuage, not implementation. Furthermore, the best way of describing how to use a command or function is very seldom done in the same order as your code is. Do you think the "ls" command has to code for dealing with the various options in alphabetical order? Or do you think the options shouldn't be described in alphabetical order, but in the order the programmer just happens to group them?

I use block comments to explain the implementation, and POD to explain the usuage. And IMO, if you use only POD, you either have lousy manual pages, or your code is very lousy documented.

-- Abigail

I use block comments to explain the implementation, and POD to explain the usuage. And IMO, if you use only POD, you either have lousy manual pages, or your code is very lousy documented.

On several occasions a monk who we all think highly of, let me know that good code comments itself. If you choose the names of variables and functions carefully, their function in the program becomes clear without separate comments. Comments appear to have the tendency to get out of sink with the code after some reviewing/ debugging rounds. So if you don't need comments at all, your code is better in the long run. I won't claim that I can write such code although I try, and I still feel more comfortable with comments all over the place.

This of course has nothing to do with inline/EOF POD. I see the general case for EOF PODs, but I can think of modules where inline PODs come more natural. If the module only exports a series of reasonable independent functions (so no OO), the interface-PODs can perfectly stay with the exported functions. But even than general usage and example docs are probably better situated EOF.

Jeroen
"We are not alone"(FZ)

On several occasions a monk who we all think highly of, let me know that good code comments itself. If you choose the names of variables and functions carefully, their function in the program becomes clear without separate comments.

Yeah, I've heard that before too. K&P write that too. And it's certainly true that well written code needs less comments. It avoids micro comments, of the style "add one to the number of elements". However, in general well choosen names of variables don't explain *why* certain actions are taken. At best they tell us what is going on. And usually, they don't tell enough of the global picture, an entire block or function. Names alone don't tell us why statements have to be done in a certain order - they don't show pre- or post conditions.

I know only one program of substantial size that's commented only sparsely, and that's perl. But I've never heard that code is easy to grasp...

-- Abigail

There are modules that are intended for users that are developers, and these may need very detailed technical documentation, or even documentation about the implementation of certain features.

In my personal experience with Perl, I'd say to these people: read the code now, you will, anyway.

In general, I think POD syntax is the problem here, not the idea of "inline" vs. "EOF" documentation. If POD syntax would waste less screenspace, everybody would use "inline" POD for implementation-level documentation.

Christian Lemburg
Brainbench MVP for Perl
http://www.brainbench.com

There are modules that are intended for users that are developers, and these may need very detailed technical documentation, or even documentation about the implementation of certain features.

I doubt that very much. Except for use in a classroom, modules are written to be used. Even if the users are developers. Not to be picked apart and their implementation studied. gdb wasn't written so people could study its implementation, was it? Sure, some people using a module will maintain it. But it's only for hardly used modules were maintainers are a significant number.

In general, I think POD syntax is the problem here, not the idea of "inline" vs. "EOF" documentation. If POD syntax would waste less screenspace, everybody would use "inline" POD for implementation-level documentation.

Well, that's quite opposite of one of my reason not to use inline POD. Changing the syntax of POD to use less screenspace doesn't solve the problem of having the documentation in the same order as the subroutines. What makes you think noone will bother about order of documentation as soon as POD stops wasting screenspace?

-- Abigail

Not to sound too AOL, but "me too!" The poor readability of the code is the main reason I dislike inline POD. It makes it really hard to quickly scan for things. And it sometimes hoses emacs.

If enough of us will use inline POD, it will become more standard, and editors will accomodate for it.

To improve readability, what about adding some lines before and after POD comments, like:

################## POD documentation begin #######
=pod

B<fetch_paper()>

Retrieves paper from environment and returns it. Should be wrapped
in an C<eval{}> to catch errors.

Returns: L<My::Paper> object.

=cut
################## POD documentation end #######
sub fetch_paper {
    my ( $self ) = @_;
    ...
}
[download]

Avoiding to 'commute' between sub code and doc comments is exactly the 'good' lazines we highly esteem, right?

Update:I also agree that sometimes the order of inline POD doc might be not the most beneficial, and sometimes info might belong to more than one module. I do not know yet how to solve this.

One of possible solution (for CGI applications) might be to use CGI::Application, which allows to wrap multiple programs as "run modes" into one module. Then, I can write sub in order as it makes sense in documentation.

As I said, I do not have solution, only weak preferences.

That is why I wnat to listen to insight from other monks, to see that other questions meight be asked, and what I forgot to consider.

What a great place is our monastery!

pmas

To make errors is human. But to make million errors per second, you need a computer.

Right on. I used to hate POD, and then I found a perl highlighting mode for emacs that highlights it properly. Now I hate that I haven't used it thus far, because it really reminds you to step back and examine your code as a critical observer.

If I knew LISP, I'd try to extend emacs to do funky visual things when it sees POD, like make the background for the entire width of that visual line a different colour or something. But alas, I don't :-(

I am using MultiEdit.

Comments have one background color, inline POD has different background color. Easy to see what is POD text, what are comments, and what is code (white background). Of course syntax coloring for both HTML and Perl.
Also I have templates expanded by space (i.e. after "if ", "wh ", or "sub ". Smart indent. Integrated FTP. Integrated compiler and compiler errors. Integrated C-like macro-language. And more...I am happy... ;-)

pmas
To make errors is human. But to make million errors per second, you need a computer.

I hate inline POD. It distracts from the code, and occupies far too much screen space due to the paragraph oriented syntax, combined with the low level granularity of the markup (e.g., try making up a bulleted list of arguments for a given function - you don't see the function anymore, it's all POD).

Personally, I am much in favor of the solution of Lisp and Python: the docstring. In this approach, the first comment after the function definition is taken as documentation for the function. Because of this, code browsers can extract the documentation for the function easily.

Christian Lemburg
Brainbench MVP for Perl
http://www.brainbench.com

I have found javadoc pretty decent for this as well. It doesn't use a screen-eating paragraph-oriented syntax -- although if you want to do anything like bulleted lists, code formatting, etc., you just use HTML, which isn't necessarily the best solution either. Most Java editors will generate the javadoc skeleton from the method signature for you as well, which is nice. (This gets into a separate point about POD -- inconsistent formatting -- which should be the subject of a separate discussion.)

I agree with your comments about screen real-estate -- this is one of my main objections to inline POD. And if we were doing docs solely for code browsers then, clearly, we don't want it to get in the way of coders reading code.

But this problem with docs and code getting out of sync is a real one, and my personal experience (because I can be in-the-bad-way lazy) is that the docs suffer if I don't do inline POD. They'll get done eventually, but usually they get done all at once (when I do "doc writing" code sweeps) rather than at the time of coding which tends to sweep nuances and details under the rug.

Perhaps I just need to train myself better and develop good habits like Kent Beck :-)

Chris
M-x auto-bs-mode

But this problem with docs and code getting out of sync is a real one, and my personal experience (because I can be in-the-bad-way lazy) is that the docs suffer if I don't do inline POD.

You are definitively right here. My personal (bad?) solution to this problem is to write documentation for the user aspect of a module only - and for this I find the "doc writing code sweep" approach quite OK, since the user interface should not change often anyway.

For the rest, I use comments. All in all, I mostly try to write "self-documenting code". But alas, I am not the one to ascertain if I succeed in this.

The worst problem with all this, IMHO, is that there is really no other way to document the interface to your function in the code than by clever paramater naming. And even that is in vain for return parameters. And that in a language that can have an arbitrary number of them, and without types. This is a really weak point in Perl (no way to express function signatures with return types in the code).

What I found in practical work is: you really need to read the code you call. If something does not work as expected, and you are sure your code is not the problem, go and read the code you call (with a nice debugger this is much easier than one thinks).

Christian Lemburg
Brainbench MVP for Perl
http://www.brainbench.com

Actually, since you're documenting your subs anyway (you are, aren't you? ;), what's the point of using # when the alternative (POD) is machine readable? Using CPAN modules nota bene, you don't have to make up your own doc-to-HTML-or-whatnot standard like in so many other languages.

The one disadvantage I can see would possible be performance, but I think it's kind of easy on the parser to skip POD markup as opposed to making sense of Perl code :)

These are my templates for documenting properties and methods:

=head2 ppp

The what that is this and that.

=cut
sub ppp { my $self = shift;


=head2 mmm()

Do this, do that.

Return 1 on success, else 0.

=cut
sub mmm { my $self = shift;
[download]

/J

Actually, since you're documenting your subs anyway (you are, aren't you? ;), what's the point of using # when the alternative (POD) is machine readable?

My, the existance of the podlators of course!

Here's some example block comments (and the matching code that is being commented) I wrote when implementing chmod in Perl.

            # BSD documentation says 'X' is to be ignored unless
            # the operator is '+'. GNU, HP, SunOS and Solaris handle
            # '-' and '=', while OpenBSD ignores only '-'.
            # Solaris, HP and OpenBSD all turn a file with permission
            # 666 to a file with permission 000 if chmod =X is
            # is applied on it. SunOS and GNU act as if chmod = was
            # applied to it. I cannot find out what the reasoning
            # behind the choices of Solaris, HP and OpenBSD is.
            # GNU and SunOS seem to ignore the 'X', which, after
            # careful studying of the documentation seems to be
            # the right choice.
            # Therefore, remove any 'X' if the operator ain't '+';
            $perms =~ s/X+//g unless $operator eq '+';


                    # We know the operator eq '+'.
                    # Permission of `X' is special. If used on a regul
+ar file,
                    # the execution bit will only be turned on if any 
+of the
                    # execution bits of the _unmodified_ file are turn
+ed on.
                    # That is,
                    #      chmod 600 file; chmod u+x,a+X file;
                    # should result in the file having permission 700,
+ not 711.
                    # GNU and SunOS get this wrong;
                    # Solaris, HP and OpenBSD get it right.
                    next unless -d $file || grep {$orig {$_} & 1} @ugo
+;
[download]

Should all of that appear in the manual page? No, of course not. This is the "matching" POD:

=item B<X>

The execute permission bit, but only if the target is either a directo
+ry,
or has at least one execution bit set in the unmodified permission
bits. Furthermore, this permission is ignored if I<operator> is either
B<E<45>> or B<E<61>>.
[download]

-- Abigail

Of course I'm commenting subs! :-)

One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate. OTOH, you can do something like:

=begin todo

Please change the variable names to something less cryptic. Anyone?

=end todo
[download]

I've been meaning to play around with the nifty-looking Pod::POM module which would make data gathering easy for stuff like this -- for instance, finding out all the TODO items for multiple projects at once.

Chris
M-x auto-bs-mode

One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate.

Very true. My personal guideline is this:

• Interface - POD
• Implemenatation - Perl comment
/J

Inline POD certainly restricts the possible format of your documentation. Win32::TieRegistry's documentation would suck by comparison if I tried to use inline POD for it.

The advantage of inline POD is that you can keep the documentation of the interface close to the definition of the interface. The problems with that are that 1) good POD should contain a lot more than just the documentation of the interface and 2) Perl doesn't let you define an interface other than via its implementation.

So inline POD forces the co-mingling of the implementation and lots of non-interface documentation (like examples, explanations, etc.). This can easily make the implementation fragmented and harder to understand/maintain and make the documentation fragmented and harder to understand/maintain.

Now, if Perl offered interface declarations (like subroutine prototypes in many other languages), then I'd likely co-mingle those into the POD.

But I mostly don't use co-mingled POD because I think it leads to pretty ugly documentation. I like to control the flow of the documentation in hopes of making it easy to understand and also control the flow of the code for the same reason. These goals usually don't lead to the code being in the same order as the POD so I usually don't co-mingle them.

Update: Yes, Perl subroutine declarations, especially of OO methods, only define a name and so are pretty useless. If Perl had "more traditional" subroutine declarations, than changing the interface w/o updating the documentation (where the declaration is co-mingled) should produce an error about mismatched prototypes in order to remind you to update the documentation.

        - tye (but my friends call me "Tye")

Tye, you could declare your subs at the top mixed in with the POD. But I don't see what that would buy you, over just having the POD there.

You echo my feelings: inline POD means that the documentation follows the code's organization. Documentation needs its own organization for different purposes: tutorial, group explainations of related functions, etc. Inline documentation would also require some kind of "literate programming" process as well.

—John