Documenting cgi programs 2

[philote]

I'm looking for some good suggestions on how to document perl cgi scripts, both internal documentation and external. I want to be sure that if/when I leave my current job that my successor doesn't have to wade through my not-so-clean code to figure out what the heck I'm doing. It'll also help me at a later date when going back to the code to make changes. I'm really looking for a good way or layout for creating a document that tells what each script does, how they interrelate, requirements, etc.



Kevin
A+, Network+, MCP

 

[PaulTEG]

Kevin,

I seem to remember a discussion on POD as being the preferred standard for Perl

Have a look on

http://search.cpan.org

HTH
--Paul

 

[philote]

Thanks, I researched POD but its not exactly what I'm looking for. I want to know what is good to include in documentation for cgi scripts. If anyone has some documentation they could share I'd love to see it. I'm not really too concerned right now with internal documentation but instead want to produce some hard copy of what my cgi scripts are doing and how they work. As a programmer, what kind of documentation would you like to receive if you suddenly inherit a small company's web site and cgi scripts?


I apologize if this thread doesn't fit this forum too well but I didn't know which forum would be more appropriate.

Kevin
A+, Network+, MCP

 

[PaulTEG]

Kevin,
Contact names, department, telephones, and a short descriptive passage on what the script does, and what other artifacts its related to would be nice at the start of the script.

In line documentation for the code where it struts its funky stuff. If you can structure regexes, and complex code in an ordered way where it can be easily documented.

Have readable code is a big thing if you're thinking of other people.

Tearing a strip out of POD, you can write a script to pull your header block, and all documentation related to subroutines
#!/usr/bin/perl
# Comment Block:
#
#
# Comment End:
program
# Comments
sub sub1{
# Comments
whatever sub1 does
}
...

Just a thought
--Paul

 

[philote]

Great, thanks!

Kevin
A+, Network+, MCP

 

[tviman]

Kevin,

As a veteran of reverse code engineering, if you're going to document your code, PLEASE, PLEASE, PLEASE make sure you document exactly what your variables are, what they do, and where they're used. Especially if they pass values on to other scripts and/or sub routines.

Also, it never hurts to write a brief description of what your for and while loops do and what you expect from them, especially when it comes to manipulating arrays or creating any dynamic values.

Documenting code is time consuming and sometimes not worth the effort. More companies than you can imagine don't want to be paying a programmer to document their code - and that's a shame. I applaud your intentions and hope you follow through with it.

There's always a better way. The fun is trying to find it!

 

[philote]

Well, after professors pounding in my head the importance of documentation and trying to decipher code I wrote, I definitely feel I should document my programs. The last place I worked made it a practice to create external documentation for all programs, but these were just high-level descriptions of what they did. There were few programs with much, if any, internal documentation and I even got in trouble for making my code too bloated with comments.

Anyway, thanks for the advice. Can anyone post some examples of any kind of decent documenation?

Kevin
A+, Network+, MCP

 

[philote]

I'm still not really getting what I'm looking for. I'm trying to get a format for some external documentation for each cgi application. I've been thinking about it more and I think I know some of what I'd want in my docs. I'd have a summary of what the application does, then maybe a list of the files involved and a short summary of each. Then perhaps a more in depth summary of each program/file telling what different views they'd present to the user, which other programs/files they interact with and how(parameters passed), and what parameters it passes to itself. Does this make sense and would there be anything else that could be useful? And does anyone else keep this kind of documentation or do you just have internal documentation or none at all?

Is there a better forum I could have posted this in?

Kevin
A+, Network+, MCP

 

[PaulTEG]

The best form of documentation is 'living'. Where the knowledge is implicit to the organisation, because the guy/gal that wrote it is still responsible for it, and is still employed by the organisation. After that, "ahh F&*U that, ring his momma, and see if she'll get him/her to talk to us ...", putting none of my 401 on that sH1T.

It's gona get harder to pass a really good idea off to middle managers because its gonna impinge on their timelines -> budgets.

Before really tackling a project like this, I'd search out the head honcho, and tell them "I'll save you shitloads later if you add 10% now".

The level of documentation you prescribe is admirable, but there's a cost, and most developers consider their work above reproach
#
Have Fun (ds)
--Paul

They're business people after all, and some stats have been done on this in the past

 

[ChrisHunt]

I'd advise you to do as much of documentation as possible inline, or as headers for the program files themselves. Documentation that lives in a seperate document is almost bound to get out-of-step with the code it (supposedly) describes.

As a contractor often employed to maintain or modify other peoples' code, I've learnt to ignore what documents say should be happening and concentrate on looking through the code to see what IS happening - they're rarely the same thing. Clear & commented code helps that process.

-- Chris Hunt

http://www.extracon.com

http://www.mcgonagall-online.org.uk

http://www.napitalia.org.uk

http://www.leicesteryha.org.uk

 

[philote]

Thanks for the advise, Chris. I'll probably still do some sort of external documentation with just a high-level description of what the programs do but after reading your post I probably won't go into the depth I was planning before.

Kevin
A+, Network+, MCP

 

[tviman]

Kevin,

here's an example of a "header" style documentation that I use. if it works for you, modify it to suit your needs:
(I keep a blank copy of this as a text file and "cut-paste" into new scripts I start)

#SCRIPT NAME ORIGIN DATE SCRIPT DOES???
#xyz.cgi 12/12/1211 sends form data via email
#
#MODIFY DATE PROGRAMMER DESCRIBE MODIFICATION
# 01/12/1311 Fred Frick added form field to email
#
#CALLED FROM ROUTINES USED EXPLANATION #xyz.html none
#
#VARIABLES SCOPE TYPE EXPLANATION # $x private char this value
# $y private numeric for loop counter
# $z global array form field values
#
#TABLES/FILES USED INDEXES EXPLANATION
# xyz.txt none email addresses
# abc.dbf none user names/passwords

Chris and Paul are both absolutely correct in that: 1) external documentation rarely resembles the actual code. 2) managers/supervisors have a budget they're tied to and I can tell you from experience, documentation is NEVER a part of that budget.

And unless the head honcho has actual experienced the agony of deciphering what a program does, it's doubtful that he/she will understand the importance of spending the extra sheckles for proper code documentation.

There's always a better way. The fun is trying to find it!

 

[PaulTEG]

Hear Here

It's important in life to always strike a happy medium, so if you see someone with a crystal ball, and a smile on their face ...

 

[philote]

Thanks tviman! That'll help a ton.

I'm in a pretty unique position where I'm the first and only IT person in our small company. Though I was told explicitly when hired that this is not a programming position I've been creating some small cgi apps to make people's lives easier. Being the entire IT department I, for the most part, get to decide what I spend my time on; meaning I can document to my heart's content. Which is what I want to do because the number of apps I've make/am making is starting to grow. Instead of spending too much time down the road making changes to these apps because I've forgotton exactly how they work, I want to spend the extra time now creating good documentation. Plus, I won't be with this company forever and feel sorry for the poor fool that replaces me.

While I've done plenty of documentation in school with c++ programs and in my previous job with an ancient report-generation language, cgi is quite different. I haven't before had to document a program that accepts user input, connects to databases, and can create different user interfaces depending on the state its in. Which brings me to another question: Does anyone create state diagrams, or any other diagrams for that matter, for their cgi apps?

Thanks again to everyone who's responded.

Kevin
A+, Network+, MCP

 

[PaulTEG]

When documenting, use anything YOU feel will add to the package.

--Paul