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
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)
| [reply] [Watch: Dir/Any] |
|
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
| [reply] [Watch: Dir/Any] |
|
| [reply] [Watch: Dir/Any] |
|
|
|
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
| [reply] [Watch: Dir/Any] |
|
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
| [reply] [Watch: Dir/Any] |
|
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
| [reply] [Watch: Dir/Any] |
|
|
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. | [reply] [Watch: Dir/Any] |
|
|