No sweat. Me? i don't scatter pod. I 'cluster' it in
one spot - i like mine at the very end. When i need to
modify the POD, i use a split-screen mode in my text editor.
That way i can see the method i am documenting easily.
Remember, you are
not suppose to be reading the POD while you are reading
the code (i.e., in your text editor), you are suppose be reading POD via a POD viewer (perldoc). Second, small
meaningless stuff is not even worthy of comments in the
first place, IMHO. I will use a single # comment to put an
author's name in if i grab code from the Monastery, but
other than that, i don't bother. It is a waste of
time. It's hard enough to keep the POD current with the
code, why add another layer? (see Re (tilly) 2 (disagree): Another commenting question, for more on
that.)
And while your suggestion of substituting in warn
has been duly noted, that final blurb was an 'inside joke',
a reference to the infamous use CGI or die; write up. I'll
leave it intact, thank you. ;)
use POD or die $!;
UPDATE:
I almost forgot about using POD as multi-line comments.
Personally, i think that # comments are the uglier of the
two:
# function: foo
# input : bar baz
# output : qux
# precond : bar and baz are defined
# postcond: qux is defined
sub foo {
}
versus
=for comment
function: foo
input : bar baz
output : qux
precond : bar and baz are defined
postcond: qux is defined
=cut
sub foo {
}
Two extra lines, but you don't have to worry about
prepending #'s. You don't have to have 'valid' POD to
create a multi-line comment, by the way. Just a simple
=for token to start and =cut to end.
UPDATE2
sigh ... you missed my points completely ... did you
even read tilly's post?
jeffa
L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)
| [reply]
[d/l]
[select] |
Ok... blow by blow ;-)
" you are not suppose to be reading the POD while you are reading the code"
But I am suppost to document while coding
It's hard enough to keep the POD current with the code
I know.. that's why you shouldn't over-use it :-)
I'll leave it intact, thank you. ;)
Be brave! Drop tradition! hehe..
BTW: Are you sure the second one looks better? Must be a matter of taste? ;-)
| [reply] |
Nah, i don't think I've missed your point, but I do think commenting style is a matter of taste, and as long as it's serves it's purpose, documentation, it's not a major issue.
That's also why my reply was intended to be more about humor than anything else.
| [reply] |