denbeste@cc5.bbn.com.BBN.COM (Steven Den Beste) (07/25/87)
OK - I am a great proponent of structured design around here, and have been
proseletyzing about it anyway, so maybe I am a good person to describe just
what it is.
It starts with three axioms:
1. Everyone makes mistakes.
2. The earlier a bug is found, the cheaper it is to correct.
3. Code is easy. Interfaces are hard.
[It is typically a good test of the professional experience of a person whether
they agree with these three statements. There is a good correlation
between years in the industry and how many of them a person agrees with.]
To answer these problems, three answers respectively:
Answer 1: Everything that anyone does is checked by someone else.
Answer 2: This checking is done as early as possible
Answer 3: Design it completely before you code it.
The stages of the project using structured design are as follows:
A. SPECIFICATION: Write the user manual FIRST!! [I'm not kidding! Figure
out what you are going to do before you start working on any of it! Not
doing this is THE classic novice's mistake.]
B. ARCHITECTURE: Figure out the functional breakdown and DOCUMENT IT.
C. DETAILED DESIGN: FIgure out precisely what every module and data structure
is and DOCUMENT IT.
[Note: At this point, 1/2 of total project time has passed. No code has been
written. Project documentation may fill many notebooks.]
D. CODE AND DEBUG
E. SYSTEM INTEGRATION
F. Q/A
After any document is written, everyone on the project team reads it and makes
comments.
After any code module is written, two other project team members read and make
comments, after the first clean assembly/compile but before debugging begins.
The idea is that most projects get into trouble during the system integration
phase, because at that point they have a lot of code modules which are solid
inside, but don't fit to each other - so some gross hack-stuff is put in
between (sort of like mortar) to make them fit - and it never works perfectly,
and catastrophically fails when you least expect it. (Oh, hi there, mister
Guru!)].
With Structured design, you design the interfaces before you do the insides.
Fundamentally, Structured design is top-down: Worry about the interfaces first
and the internals of the modules later.
The traditional approach is bottom-up: Kick into the code, and worry about how
to fit it together later. The usual objection of a traditional programmer to
Structured design is "I'm a programmer - I'm here to code. Why the hell do you
want me to do all that useless documentation?"
A parallel comparison of the two approaches can make Structured design look
bad part way through: Half way through the project the Structured design team
hasn't written a line of code, while the traditionalists may have 80% of the
code written, and even running somewhat.
By project end, the Structured design team is done, on schedule, with low bug
rate. The traditionalists have overrun their Q/A schedule fourfold and are
still chasing integration problems.
Understand, this is an extremely brief description of the technique. Also
understand that as projects get smaller the benefits of the technique get
less. For a 1-month project with one person, most of it can be skipped. For a
three year project of 10 people, it is indispensable. (I know - I was on one.)
The same three year project of 10 people done in the traditional approach will
take 4.5 years...
--
Steven C. Den Beste
Bolt Beranek & Newman, Cambridge MA
denbeste@bbn.com (ARPA or CSNET)hadeishi@husc4.HARVARD.EDU (mitsuharu hadeishi) (07/31/87)
In article <469@cc5.bbn.com.BBN.COM> denbeste@cc5.bbn.com.BBN.COM (Steven Den Beste) writes: >The stages of the project using structured design are as follows: > >A. SPECIFICATION: Write the user manual FIRST!! [I'm not kidding! Figure > out what you are going to do before you start working on any of it! Not > doing this is THE classic novice's mistake.] > >B. ARCHITECTURE: Figure out the functional breakdown and DOCUMENT IT. > >C. DETAILED DESIGN: FIgure out precisely what every module and data structure > is and DOCUMENT IT. B. should be expounded upon somewhat. A common mistake is to design the data structures before you have designed the logical structure of the program. The data structures should ALWAYS BE DESIGNED LAST. Another way of putting this is "form should follow function," i.e., the form of the data should follow the design of the functionality. A good way to work on this is to generate rough outlines of the code in psuedocode, and only at the last possible moment design the details of the data structures. At that point it should be clear what the optimal data structure design should be, since it will follow from the logical structure of the program. Psuedocoding should precede data structure design which should precede the final stage of actual coding. If this procedure is followed it should be possible to write program modules that are clean, properly documented, and bug-free. (Yes, BUG-FREE.) >Understand, this is an extremely brief description of the technique. Also >understand that as projects get smaller the benefits of the technique get >less. For a 1-month project with one person, most of it can be skipped. For a The essential principles of structured design are still important and very beneficial even when only one person is involved (although of course peer review cannot occur.) In particular the idea of writing documentation and designing data structures last, after psuedocoding, is of immense use and if applied rigorously can lead to wholly bug-free programs, even on the first run. -Mitsu
elg@killer.UUCP (Eric Green) (08/01/87)
in article <469@cc5.bbn.com.BBN.COM>, denbeste@cc5.bbn.com.BBN.COM (Steven Den Beste) says: > Answer 3: Design it completely before you code it. Easier said than done. You have to design it using SOME language, after all! Considering that a lot of these programmers know more Fortran than English.... :-) :-) :-) :-). > A. SPECIFICATION: Write the user manual FIRST!! [I'm not kidding! Figure > out what you are going to do before you start working on any of it! Not > doing this is THE classic novice's mistake.] Definitely! AMEN! Too often, the documentation is put off, with "well, we can do that later, we're too busy programming right now".... and someone wonders why the user manual is delaying the project, and why there's awkward errors in the user manual (answer: the documentation folks were writing the manual at the same time the programmers were writing the program, and there's no way for the commmunications to be tight enuf for the left hand to know what the right is doing!). > B. ARCHITECTURE: Figure out the functional breakdown and DOCUMENT IT. Hmm.... a lot of the time, you don't KNOW what the architecture of the program is going to be like, until you have sketched out some major algorithms and data structures.... But, still, in general, this is good advise. > C. DETAILED DESIGN: FIgure out precisely what every module and data structure > is and DOCUMENT IT. Hmm. Here's where I start seeing diminishing returns. You are essentially programming in English instead of in "C" when you reach this point. And, as I mentioned, most programmers are more comfortable with "C" than with English. in general, I don't advocate a level of pre-coding design more complex than breaking the project down into man-sized chunks, and describing the major data structures and algorithms involved, and the major routines and their interface requirements. A well-designed project consists of a number of black boxes, with designer of one box having no need to know the contents of another box. Excruciatingly precise design documents of box internals therefore would be self-defeating, burying the poor programmer in tons of stuff he doesn't need to know. Requiring internal documentation of every module and data structure describing its purpoe, range of values, and parameters is MUCH more useful, espcially if the documentation is in a special format such that it can be easily extracted via a "sed" script or such in order to make a master interface manual.... > to fit it together later. The usual objection of a traditional programmer to > Structured design is "I'm a programmer - I'm here to code. Why the hell do you > want me to do all that useless documentation?" Because I'm always looking for an easier and faster way of doing things. I get tired of working on the same old project month after month, and have been known to go to ridiculous lengths to find just the right tools to make my job easier, so I can go on to newer and better things. -- Eric Green elg%usl.CSNET Ollie North for President: {cbosgd,ihnp4}!killer!elg A man we can believe (in). Snail Mail P.O. Box 92191 Lafayette, LA 70509 BBS phone #: 318-984-3854 300/1200 baud
fnf@mcdsun.UUCP (Fred Fish) (08/03/87)
In article <1267@killer.UUCP> elg@killer.UUCP (Eric Green) writes:
-> [stuff deleted...]
->to know. Requiring internal documentation of every module and data structure
->describing its purpoe, range of values, and parameters is MUCH more useful,
->espcially if the documentation is in a special format such that it can be
->easily extracted via a "sed" script or such in order to make a master
->interface manual....
-> [more stuff deleted...]
->Because I'm always looking for an easier and faster way of doing things. I get
->tired of working on the same old project month after month, and have been
->known to go to ridiculous lengths to find just the right tools to make my job
->easier, so I can go on to newer and better things.
Given the above philosophy (internal documentation in each module and
a way to mechanically get that translated into a external form of
documentation) you should check out my "dex" program on my library
disk 14. This extracts internal documentation inside C comments, in
the general "manual page" form, and converts it to nroff source.
I haven't used it much in a couple of years, since I've pretty much
been stuck fixing other people's code for about that long, rather
than producing brand new code. It probably still has a few rough
edges (it was one of my first pieces of C code) but might be a good
base for trying new techniques and features.
P.S. I got the general idea from the Decus C kit, where the
documentation was kept in the source files.
-Fred
--
= Drug tests; just say *NO*!
= Fred Fish Motorola Computer Division, 3013 S 52nd St, Tempe, Az 85282 USA
= seismo!noao!mcdsun!fnf (602) 438-3614bryce@COGSCI.BERKELEY.EDU (Bryce Nesbitt) (08/03/87)
[ Sigh, UCB's net news disk filled up. I got numbers, but no actual text to go with them. Sorta like the lineeater's big brother :-) Or perhaps Robert W. Skyles; his company sends me royalty reports... but no checks! :-( ] In article <1267@killer.UUCP> elg@killer.UUCP (Eric Green) writes: >in article <469@>, denbeste@cc5.bbn.com.BBN.COM (Steven Den Beste) says: > >> A. SPECIFICATION: Write the user manual FIRST!! [I'm not kidding! Figure >> out what you are going to do before you start working on any of it! Not >> doing this is THE classic novice's mistake.] > >Definitely! AMEN! Too often, the documentation is put off [till later]... >...and someone wonders... >why there's awkward errors in the user manual... I once worked on a project like that. We had the opposite problem; it turned out to be a *major* pain to conform the software to the poorly written manual! [ The situation was real, every other implication of this posting gets lots of :-) :-) :-) warnings! ] ----- |\ /| . Ack! (NAK, EOT, SOH) {o O} . Use the address below, and no other... ( " ) bryce@cogsci.berkeley.EDU -or- ucbvax!cogsci!bryce U "Apparently, Ma Bell is Uncle Sam's wife."