Dean_Thompson@TRANSARC.COM (08/05/90)
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.
"module level" -- In addition, give an exact interface for each module.
"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.
I am interested in your experience with:
- How long a particular level of design documentation takes.
- How much of this time is repayed by faster coding.
- How particular levels of design documentation influence the ultimate
buginess of the code.
- How particular levels influence the ultimate cleanliness of the code
structure.
- How useful particular levels turn out to be for maintenance.
I'm much more interested in specific experiences than philosophy.
Dean Thompson
Transarc Corporation
dt@transarc.compsrc@mtunq.ATT.COM (Paul S. R. Chisholm) (08/05/90)
There's an implicit assumption here: that design documentation is done in English (or Japanese, or whatever) prose. To what extent have people had good luck with other forms, e.g., data flow diagrams, data dictionaries, structure charts, as documentation? (By "success", I mean both "success in creating or generating such documentation", and "doing anything with such documentation when maintenance time comes along, and keeping such documentation up-to-date".) Paul S. R. Chisholm, AT&T Bell Laboratories att!mtunq!psrc, psrc@mtunq.att.com, AT&T Mail !psrchisholm I'm not speaking for the company, I'm just speaking my mind.
wags@cimage.com (Bill Wagner/1000000) (08/06/90)
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
jjj@polari.UUCP (Jeff J) (08/06/90)
In article <Eail8ur0BwwAEiGEo8@transarc.com> Dean_Thompson@TRANSARC.COM writes: >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. > >"module level" -- In addition, give an exact interface for each module. > >"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. In my experience the biggest problems have come at the beginning of the project life cycle. If the initial analysis and requirements are not done with care all the design documentation in the world will not be worth anything. The most important place to put in the time documenting and to have objective reviews is in the early phase of a project. Any mistakes made here are a lot more costly then those made at the coding level. A code bug is easy to fix. A design error is far more costly. Of course this has to be balanced by a consideration of risk. For example, if a module is relatively small and straight ahead I would think the only documentation needed would be a clear statement of what the module does and a list of tests that will verify its requirements. From that point on I would only expect the programmer to maintain minimal shop standards. The shop I work in is in the process of redoing our software (we develop administrative software for the WA public schools). We have out grown the orginal designs and had gotton ourselves into the position of spending most of our time maintaining the old rather then developing new needed software. Consequently we are now spending millions redoing everything. Had more care been put into good design we might have avoided this expensive project although from what I've heard this problem is common to a lot of companies. I think the key to good software development is not in the coding, but in making sure you are truly meeting your user's needs at every stage of the project and the sooner in the project life cycle these needs are determined the easier it will be to bring the project to a successful conclusion.
Dean_Thompson@TRANSARC.COM (08/06/90)
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
davecb@yunexus.YorkU.CA (David Collier-Brown) (08/07/90)
In article <Eail8ur0BwwAEiGEo8@transarc.com> Dean_Thompson@TRANSARC.COM writes: | 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. | | "module level" -- In addition, give an exact interface for each module. | | "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. Alas, that's ALL low-level. The first makes a good technical paper, of interest to people working on the software, and the second makes a good interface (Ada) or .h (C) file. But first you need a statement of what it's going to do, for whom, and why. Check out the Project Athena Technical Plan for an example: various parts are obtainable via ftp. My preferred approach is to write the user manual first, and then get it checked by 1) the marketdroids, to see if i **have** a real product (carefully ignoring their particular suggestions (:-)) 2) the (lonely) ergonomist, to see if I have a usable product, 3) our RFP-response manager to see if it meets what the customers have been asking for (nb: NOT the marketing deptarement, I want the raw data). 4) a customer volunteer, so they know what we're proposing and have a chance to scream. Then I write a features list, order it from "in first release" to "never" by clustering capabilities, define the primitives I need to have to provide them, and write my Technical Plan, which some unlucky manager gets to sign off on. --dave (for small projects, this can be "write man page. write code") c-b -- David Collier-Brown, | davecb@Nexus.YorkU.CA, ...!yunexus!davecb or 72 Abitibi Ave., | {toronto area...}lethe!dave Willowdale, Ontario, | "And the next 8 man-months came up like CANADA. 416-223-8968 | thunder across the bay" --david kipling
mitchell@chance.uucp (George Mitchell) (08/08/90)
In article <1207@mtunq.ATT.COM> psrc@mtunq.ATT.COM (Paul S. R. Chisholm) wrote:
`There's an implicit assumption here: that design documentation is done
`in English (or Japanese, or whatever) prose. To what extent have
`people had good luck with other forms, e.g., data flow diagrams, data
`dictionaries, structure charts, as documentation?
A closely related issue that I am interested in is the replacement of
top-level documentation with tools that capture and maintain
requirements in a primarily non-verbal form. These could be CASE tools
or prototypes.
` (By "success", I
`mean both "success in creating or generating such documentation", and
`"doing anything with such documentation when maintenance time comes
`along, and keeping such documentation up-to-date".)
Also, success in getting a user/client to accept such a representation.
--
George Mitchell, MITRE, MS Z676, 7525 Colshire Dr, McLean, VA 22102
email: gmitchel@mitre.org [alt: mitchell@community-chest.mitre.org]
vmail: 703/883-6029 FAX: 703/883-5519jimad@microsoft.UUCP (Jim ADCOCK) (08/09/90)
In article <13581@yunexus.YorkU.CA| davecb@yunexus.YorkU.CA (David Collier-Brown) writes: | My preferred approach is to write the user manual first, and then get |it checked by | 1) the marketdroids, to see if i **have** a real product | (carefully ignoring their particular suggestions (:-)) | 2) the (lonely) ergonomist, to see if I have a usable product, | 3) our RFP-response manager to see if it meets what the customers | have been asking for (nb: NOT the marketing deptarement, I | want the raw data). | 4) a customer volunteer, so they know what we're proposing and | have a chance to scream. The Japanese affiliate of a prior employer of mine wouldn't start on a project until the engineers on that project had amassed at least 200 customer visits. That company won a Deming award, if I remember right.
itcp@praxis.co.uk (Tom Parke) (08/09/90)
Dean_Thompson@TRANSARC.COM writes: >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. >"module level" -- In addition, give an exact interface for each module. >"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. Whoa, this is all implementation. What you need to do depends on the context. Who is for, your self, your friends, your company, for sale, for a client? How big is it? How many people will be writing it? How many versions will there be? How safe and reliable does it have to be? How long will it last. How long will it last really :-). Are you experienced in the technology (hardware, operating system, language, development environment) to be used in the implementation? If the software is for somebody else (they're paying for it) how much do they understand computers and software? How much do you understand their business? Remember never assume immaculate conception, everything you do is to try and find where you are going wrong as soon as you can :-). Tom -- Tom Parke (my opinions and spelling are strictly temporary) itcp@praxis.co.uk Praxis, 20 Manvers St., Bath BA1 1PX, UK