Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

Inline POD vs. EOF POD

by lachoy (Parson)
on Jul 09, 2001 at 17:32 UTC ( #94969=perlmeditation: print w/ replies, xml ) Need Help??

Yes, it's another commenting node. But wait! It's constrained to a simple (?) topic which, AFAICT through super search, hasn't been discussed directly before:

Which POD commenting style do you prefer: inline POD or end-of-file POD? (examples of both below)

Personally, I'm ambivalent. (If I weren't, I wouldn't be asking for an opinion, right?)

I like inline POD because it keeps the code and docs closer together. This doesn't ensure that both get updated at the same time, but it makes updating much easier. It also helps comments directly above the subroutine not get out of sync with docs in POD.

I like end-of-file POD because all the code is in one place and the docs in another -- for many people this is easier to read.

I recently posed this question to the OpenInteract developers' mailing list but didn't get much of a response. One comment I got was that editors don't get confused as easily by EOF POD. (Yes, even (X)Emacs/CPerl gets occasionally confused by inline POD.)

If I were writing code just for me, I would use inline POD. However, I'm trying to make it easier for people to get involved with some more complicated and sizeable CPAN modules, and code readability is high on the list of impediments. However, good and consistent docs are also high on that list....

Chris
M-x auto-bs-mode

Inline POD example:

package My::Class; =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS =cut use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; =pod B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. =cut sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } =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 sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut

End-of-file POD example:

package My::Class; use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. 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. =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut

Comment on Inline POD vs. EOF POD
Select or Download Code
Re: Inline POD vs. EOF POD
by andreychek (Parson) on Jul 09, 2001 at 17:49 UTC
    Heh.. you reminded me of the joke:

    Yes, I can write with either hand, I'm amphibious!

    On a more serious note.. thats an excellent question you bring up, and I'd definitely like to see others opinions on the matter too.

    Overall, I personally like inline POD better, from the coders point of view. The fact that it gets the code and documentation close together makes it much easier to keep both up to date. I'll often use POD to document my API's and such, instead of using normal comments. There are a lot of projects out there that readily admit to having poor documentation. With inline POD, there is often no excuse for such behaviour. That would be false laziness, and none of us Perl types would do that, right?? :-)

    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 :-) But I find that if you come up with a standard for how to use POD throughout your code to document functions and such, it can get easier to read with practice. Now, others reading your code will have to struggle with it at first.. but IMO, having up to date documentation is worth the added discomfort.
    -Eric
      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

Re: Inline POD vs. EOF POD
by tadman (Prior) on Jul 09, 2001 at 18:03 UTC
    I'd say the inline version is more likely to be maintained because the "commute time" between the function and the associated documentation is much shorter. If things are on the same screen, even the lazy are inclined to keep things in sync. If it's at some obscure location in the file, things might drift apart.

    BTW, here's a quick macro for 'vi' for skipping to the POD documentation in a file:      vi '+/^=pod'
    You could make this into an alias, such as 'vipod'. When it enters each file it runs the command to find the first line that begins with '=pod'. If you don't always use that tag, you can just search for the equals sign.
Re: Inline POD vs. EOF POD
by pmas (Hermit) on Jul 09, 2001 at 18:29 UTC
    I like inline POD better, too.

    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 ) = @_; ... }

    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.

Re: Inline POD vs. EOF POD
by jplindstrom (Monsignor) on Jul 09, 2001 at 19:16 UTC
    I'll have to go with the rest of the posts here and suggest that inline POD is better.

    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;

    /J

      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

      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
      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 +;
      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>>.

      -- Abigail

Re: Inline POD vs. EOF POD
by clemburg (Curate) on Jul 09, 2001 at 19:24 UTC

    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

(ichimunki) Re: Inline POD vs. EOF POD
by ichimunki (Priest) on Jul 09, 2001 at 19:55 UTC
    So far I haven't seen a comment that echos my thoughts. But I like both inline and EOF POD for two different purposes.

    Inline works great when you are writing a module, you put some POD at the beginning and the end of the file, but it's nice to have the documentation for the methods right next to the code. This still produces a very usable perldoc page.

    But for the end-user application (and I assume that this is either a shorter script or the glue script for a set of modules) I'd just put the whole POD either at the start or the end of the file since it is probably not necessary (or even desirable) to use POD to comment code.

      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

Re: Inline POD vs. EOF POD
by DrSax (Sexton) on Jul 09, 2001 at 22:19 UTC
    I understand the reasons behind inline POD, but I would have to fall into the camp of those who prefer EOF POD. This is especially true for package development. Here is my reasoning:

    I tend of think of the usefulness of POD being for the people who are going to use my package. I don't want to have to spend time explaining to my other developers how to use my class; that's why I documented it in POD so they can do perldoc MyClass. When I write the POD I do it as if I were writing documentation. Having everything in one place (at the end) makes it easier for me to see how it will look afterward.

    I think this applies very much in the case of the person who is going to use your module, and less in the case of a person who is going to modify it. So the final tally is:
    EOF POD is for class re-use.
    inline POD is better for cooperative development.

    Brian - a.k.a. DrSax
Re: Inline POD vs. EOF POD
by Abigail (Deacon) on Jul 10, 2001 at 00:10 UTC
    I very rarely use "inline" POD. I'd say never, but since I write Japhs, I rather not say never. For serious code, I *always* use EOF POD.

    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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://94969]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (6)
As of 2014-08-01 09:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Who would be the most fun to work for?















    Results (0 votes), past polls