[thelist] Basic Documentation Questions

[Webmaster]

At 13:05 08/02/2002 -0500, you wrote:
>What I've done so far is to first outline the general concept of what the
>program will do (needs), then create a flow chart suggesting how the process
>might work (functions), then write the code. I've done some informal
>documentation in the way of notes while creating the system, and by
>commenting in the code itself, but usually the comments need to be
>re-written by the time I'm done writing functional code.

My preferred method is to use the "pseudocode" method recommended by Steve
McConnell in his excellent book "Code Complete". After writing the
functional spec (what the program is supposed to do) I start writing in
detail what processes the program must perform, e.g. (simplistic example):

open database connection
search for record with title field matching entered text
if there is a match
display record
else
display error message
end if
close database connection

I then break it down into increasing levels of detail, until as McConnell
says, it's easier to just write the code. This is really helpful in making
sure I have thought about all the possible paths through the code, errors
that might occur etc. Writing the code is *much* easier if you've done all
this thinking before you start coding. Once I'm ready to start writing the
code, I convert all the pseudocode into comments, insert the actual code
and voila -- a self-documenting program!

Note: this only covers in-code docs. It is not a substitute for the proper
written spec you should have before starting to code, or any user
documentation you might produce afterwards.

HTH
Veronica Yuill                 email: veronicay at archetype-it.com
Archetype Information Technology Ltd  http://www.archetype-it.com/english/
------------------------------------------------------------------
Dynamic websites for fast-moving businesses