[Pdx-pm] Documentation Templates for CGI scripts
jkeroes at eli.net
Sat Aug 13 14:00:34 PDT 2005
On Aug 13, 2005, at 12:41 PM, Roderick A. Anderson wrote:
> to document _invisible_ scripts. Those that only a coder will look
> aren't really modules. Maybe it's my naivety but I don't see the
> pod documentation doing much good in these since they should almost
> be run from a command line.
> What I'm interested in is how those of you that write web apps
> your code.
There are three consumers of code you write:
1. You, the author
2. Other developers and code maintainers
I write different comments for all three. Let's consider your example
of a web app.
For other developers and people who will follow in my footsteps,
either maintaining code or adding features, I write POD
documentation. General methodology is explained; how all the larger
pieces fit together. How to use these pieces. Examples. Where to go
for more information.
For myself, I write comments. Why did I write a method one particular
way. Why did I use one strategy instead of another. Anything strange;
anything klugy, anything that might make me scratch my head after a
year should be commented.
Users get webpages. If they're already in a browser, why make them go
As you can see, POD is still extremely important. The only time I
don't feel obliged to write POD is for something like a
CGI::Application program, a program that has only two or three lines
of code, where the modules used are already well-documented.
Hope this helps,
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Pdx-pm-list