[thelist] Basic Documentation Questions

dan donaldson dan at omnivore.ca
Fri Feb 8 15:49:00 CST 2002


On Friday, February 8, 2002, at 12:58  PM, David at softv.net wrote:

> I recently read a very good book called "Debugging Java" which sorta
> turned
> around alot my conceptions about software development. The author
> suggests
> not only writing the documentation BEFORE writing the first line of
> code,
> but also going so far as to write the user manual before as well.
> This not only defines what the app will do, but exactly HOW it will do
> it,
> and goes a long way to help prevent "feature creep".

I agree with this statement. The first thing I taught students when I
taught programming was to pseudo-code the whole task. Top to bottom.

If you do this right, your pseudo code end up being your inline
comments, and the original copy (no code added) is the easiest way to
build flow charts, which in a larger organization is usually what you
have to start the documentation and manuals writers off with. It also is
great if you aren't sure what language(s) you'll be using. Pseudo code
forces you to be readable which is what comments should be.

I seem to recall a formula from some IBM guide written in the seventies
that said something along the lines of:

A project should be

- one third planning
- one third programming (ie writing code)
- one third QA and debugging

On a large project:

- one half planning
- one quarter programming
- one quarter QA and debugging

I know the feeling - that you just 'have' to work out ideas by writing
code. If you really do work better that way, my advice is to treat that
initial programming as part of the planning; then, write out a complete
pseudo code structure and re-program from there.

dan donaldson (new to list)




More information about the thelist mailing list