[Pdx-pm] Documentation Templates for CGI scripts

[Joshua Keroes]

On Aug 13, 2005, at 12:41 PM, Roderick A. Anderson wrote:
> how
> to document _invisible_ scripts.  Those that only a coder will look  
> but
> aren't really modules.  Maybe it's my naivety but I don't see the  
> "normal"
> pod documentation doing much good in these since they should almost  
> never
> be run from a command line.
>
> What I'm interested in is how those of you that write web apps  
> document
> your code.

There are three consumers of code you write:
1. You, the author
2. Other developers and code maintainers
3. Users

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  
elsewhere?

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,
Joshua
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.pm.org/pipermail/pdx-pm-list/attachments/20050813/d15efdf1/attachment.html