On Monday, June 10, 2002, at 05:42 , John Brooking wrote:
> Well, I confess that I sometimes use POD directives to
> write a long comment (more than about 1/2 dozen
> lines). My rationale is that I haven't really learned
> POD very well yet, and so far I haven't released any
> of this code publically. When I do, I intend to
> revisit the code and make a better distinction between
> what is properly POD doc'n and what is just code
> comments.
Another way that folks may wish to think about this problem:
a) if you are not planning to put 'pod' into your applet
then you are none the worse for wear - perse
b) you may want to think in terms of learning to 'write pod'
it really is a lot simpler in most respects than writing
either man pages or raw html
c) play with h2xs - it will give you the basic framework for
both a 'perl module' as well as the preliminary POD !
One thing I would strongly advocate against -
running 'code with major chunks of stuff commented out'
It's fine to do that while sorting out which way to go, as
strictly 'test code' when doing things like CGI development,
but when you get to that 'lock the source code tree down' -
check in the code you want, and DO NOT have chunkage of dead
code floating around - it WILL BITE YOU - someone will zone
out why this 'ugly' little '=cut' is there... and suddenly
you are off in a new morass chasing code you forgot you
left bloated around.
Solving 'what should be in the pod' as opposed to 'in code comments'
the only reasonable rule of thumb I can think of is:
a) when you are grey, and it is dark, will you remember
why you did this not so self obvious trick?
b) templatize your 'functions' so that you just have a
basic piece of commenting there anyway that you grow
or shrink as needed.
c) Expose to your user's what they should be forewarned about
either 'as pod' that also just happens to be the 'self documenting'
part you will use as well when re-writing in the dark - or have
that as a part of your
and additional stuff for other perlGeeks
POD is reasonably flexible about how you add the appropriate sections to
it.
ciao
drieux
---
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
