Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Re: Inline POD vs. EOF POD

by Abigail (Deacon)
on Jul 10, 2001 at 00:10 UTC ( #95133=note: print w/ replies, xml ) Need Help??


in reply to Inline POD vs. EOF POD

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


Comment on Re: Inline POD vs. EOF POD
Re:{2} Commenting, was: Inline POD vs. EOF POD
by jeroenes (Priest) on Jul 10, 2001 at 13:22 UTC
    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

        I'm not going to say that the perl source is a good example!

        You can use naming conventions to include the actions related to vars/functions. Like translate_buffer_to_normalized_image. Well, names get pretty long but are self-explaining. And such names can give info about pre/post conditions...

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

    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

        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.

        When it comes to the traditional CPAN module, I'm with you all the way.

        But there are other cases; consider the in-house developed program consisting of a number of classes. This is often not a case of just using a stable module or two, but a living piece of code that is indeed being changed, added to, refactored, reimplemented every once in a while.

        That was primarily what I was thinking of when stating that inline POD is useful to document interfaces. Not in a "guide" way, but in a "reference" way. If a class needs notes about intention, recommended use, etc. that should of course be part of the docs too.

        /J

Re: Re: Inline POD vs. EOF POD
by perrin (Chancellor) on Aug 15, 2001 at 21:36 UTC
    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: note [id://95133]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (8)
As of 2014-08-20 12:09 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (113 votes), past polls