Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot

Re: Inline POD vs. EOF POD

by clemburg (Curate)
on Jul 09, 2001 at 19:24 UTC ( #95005=note: print w/replies, xml ) Need Help??

in reply to Inline POD vs. EOF POD

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

Replies are listed 'Best First'.
Re: Re: Inline POD vs. EOF POD
by lachoy (Parson) on Jul 09, 2001 at 21:42 UTC

    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 :-)

    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

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://95005]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (5)
As of 2017-04-28 20:15 GMT
Find Nodes?
    Voting Booth?
    I'm a fool:

    Results (528 votes). Check out past polls.