Path: utzoo!utgpu!news-server.csri.toronto.edu!mailrus!umich!samsung!uakari.primate.wisc.edu!sdd.hp.com!decwrl!ucbvax!TRANSARC.COM!Dean_Thompson
From: Dean_Thompson@TRANSARC.COM
Newsgroups: comp.software-eng
Subject: Re: Amount of Design Documentation
Message-ID: <8ajNfCf0BwwA952_de@transarc.com>
Date: 6 Aug 90 16:29:02 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Lines: 34

Bill Wagner says (quoting me):

>>"module level" -- In addition, give an exact interface for each module.
>>
>This level is similar to the high level.  Benefits are about the same.
>This level takes me about 1 week per module.  (A module for me is
>about 500 lines, anywhere from 15-20 procedures.)
>
>>"detail level" -- In addition, describe the important algorithms and data
>>                  structures for each module.  Use psuedocode when it is the
>>                  best way to clearly describe the intended implementation.
>>
>This level is, IMHO, the throw away level of documentation.  It
>is written once, then never updated.  What I have started doing here
>is combining the prose with the real code.  That way, it is maintained
>with the code when modified.  Also, instead of writing psuedocode,
>the actual code is written.  One manager of mine stated that a good
>detailed design spec is one that compiles.  The other advantage to

One thing I have noticed is that a carefully-written ".h" file is
"a module level design spec that compiles".  Likewise, a carefully-written
".c" file is "a detailed design spec that compiles".  This certainly tempts
me to break our design process into three stages:

high level design -- a document.  Always reviewed.

module level design -- the ".h" files.  Reviewed for larger or less experienced
                       groups.

detail level design -- the ".c" files with mostly comments and very little
                       code.  Reviewed only for the least experienced
                       programmers.

Dean