Path: utzoo!attcan!uunet!decwrl!sdd.hp.com!samsung!umich!dgsi!wags From: wags@cimage.com (Bill Wagner/1000000) Newsgroups: comp.software-eng Subject: Re: Amount of Design Documentation Message-ID: <1990Aug6.151342.26763@cimage.com> Date: 6 Aug 90 15:13:42 GMT References: Reply-To: wags@cimage.com (Bill Wagner/1000000) Organization: Cimage Corp, Ann Arbor, MI Lines: 47 Dean Thompson >Based on your experience, how much design documentation do you think should >be done before coding starts? Consider the following levels: > >"high level" -- Describe important algorithms and data structures. List the > modules with a short prose description of what each will do. > This level of documentation usually takes me between 1 week, to 1 month, depending on the size and scope of the project. This is the most important part of the design documentation, IMHO, because it is the time when the overall structure, interfaces, and algoritms are stated. I find it very useful to a clean initial design. I find a high payoff in terms of faster coding, cleanliness of code. The faster coding is because you don't code yourself into corners as much. The cleanliness is for the same reason. These factors contribute to less buginess, and more easily maintained code. >"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 combining the detailed spec and the code is that you get full paragraph descriptions of procedures and smaller blocks of code. *Anyone who has maintained old code can understand what a thrill that is.* What are others experiences? -- Bill Wagner USPS net: Cimage Corporation Internet: wags@ann-arbor.cimage.com 3885 Research Park Dr. AT&Tnet: (313)-761-6523 Ann Arbor MI 48108