Manual First
Volume Number: 1
Issue Number: 8
Column Tag: Software Souffle
"Do the Manual First!
By John Bogan, Microcomputing Consultant, MacTutor Contributing
Top-Down or First Things First
With the realization around 1970 that a sense of order and discipline could be
brought to bear on the task of programming in order to enhance productivity the art of
Software Engineering blossomed and soon began to bear new fruit. One of the
observations that the Software Engineers made that seemed significant if only for its
paradoxical nature was that the earlier in a project a programmer starts coding the
longer it takes to finish the project. That is, if the first stages of a project involve
writing code then coding will dominate the entire project and you can be sure that the
project will be hopelessly late. The remedy to this problem was forthcoming, it is
called top-down design.
The pressure for jumping in and firing up the coding phase of a project is well
understood. Non-technical management often views the number of lines of code
produced as the sole measure of how far along a project has progressed. This is
profoundly wrong! Also, some programmers are not really programmers at all rather
they are more accurately coders passing themselves off as programmers. A coder is
uncomfortable unless he has an armful of complex minutia staring him in the face ... a
nice 30 page assembly language listing fills this bill quite nicely. A genuine
programmer on the other hand is capable of jumping from the detailed to the big
picture as required to keep both details and the finished product in proper perspective.
As programming projects progress beyond "toy" programs most good
programmers feel the need to build a framework for their program. This framework
is called a design and a program's design is the second most important ingredient in
determining the degree of success in a programming project. On one level the idea of a
program design is quite simple. The design of a computer program is to the finished
program as a blueprint of a building is to the finished building. One can only hope that
a contractor who builds without benefit of blueprints gets caught beneath a collapsing
wall. What is really unfortunate is that no similiar fate ever befalls programmers
who rush or even skip the design phase of a project in the misguided belief that he can
save himself a little time. After forty years of computer programming it is well
understood by computer professionals that time spent designing a serious program is
repaid tenfold during the debugging phase of a project.
After reviewing some of the literature on program design I am sure I will be able
to come back back to this topic and squeeze five or six lengthy and boring pedantic
columns out of this complex and evolving topic but for now I would like to stick to basic
principles and fundamental philosophy which I sincerely hope and believe will be of
some practical use.
The two basic approaches to computer program design are top-down and
bottom-up. Bottom-up is the classic (read: obsolete) approach to design. Bottom-up
design is characterized by an overwhelming obsession with the details of the proposed
computer program. For example, if you know you are going to print a W-2 form and
you immediately start to work on the interrupt driven printer driver then you can be
sure you are doing things bottom-up. If you find yourself hanging unplanned bells and
whistles on a program then you can be fairly certain that your program is evolving
bottom-up. If you are spending 90% of your time debugging existing code and 10% of
your time adding new features then guess what? You are doing things bottom-up.
Problems with Flowcharts
I remember in college that my instructors' idea of a design was to draw a
flowchart. So much for the benefits of college. Flowcharts as a design aid are totally
useless since everyone knows that the proper time to prepare a flowchart is after the
last bug in the code has been exterminated. The reason that a flowchart comes last is
that even miniscule changes in the program logic require serious, time consuming,
inconvenient and ugly changes to a flowchart. Adding an IF ... THEN test to a flowchart
generally requires a complete rewrite of the flawed chart. So flowcharts are clearly a
bottom-up design aid and as such are obsolete. In short, bottom-up "design" means
jumping into details with both feet as soon as possible and it is virtually the same as no
design at all. With one exception I recommend you avoid bottom-up design at all costs.
The one situation where a bottom-up approach is justified, even necessary, is
when you are trying to familiarize yourself with a new, complex computer system
(such as the Macintosh). In the case of the Mac you have about 500 powerful
subroutines to learn. It would be foolish to try to learn this library by starting with a
serious application. Instead you play ... and play and play. Try this combination of
calls and see what happens, change them around and try again. Incidently, MacPascal is
perfectly suited for this since it is highly interactive. This unstructured, or
bottom-up, approach to writing code should gradually be replaced by a more
structured approach as you gain familiarity with the tools at your disposal.
Top Down Design First!
In general, though, a much better method of attacking the design problem is to
set aside a period of time before the first line of code is written and produce some sort
of formal design. An excellent scheme for a design involves the use of the top-down
principle (also known as stepwise refinement and hierarchical decomposition.) The
top-down principle can be stated as follows: Start with the most abstract and all
encompassing description of the problem to be solved. Find the natural lines of
cleavage. Break the big problem into smaller and easier to solve subproblems and
continue until you start encountering the gory details.
Think of your program as the solution to some problem, then think of that
problem as a diamond to be cut into successive generations of smaller and smaller
diamonds and when the diamonds (problems) are small enough it will be easy to write
the code that solves the little problems.
Now, if you are still awake after that dose of theory let me show you how handily
the top-down principle translates into practical reality.
"The most abstract and all encompassing description of the problem to be solved
is really just another way of saying "User's Manual"! Folks, the JB method of
top-down design dictates that you WRITE THE USER'S MANUAL BEFORE YOU DO
ANYTHING ELSE!!! I can think of only two exceptions to this rule otherwise the first
project milestone should be the User's Manual.
Think about it.
95% of all useful computer programs are useful because they solve some
problem for some stranger. Certainly this is true for programs sold in the mass
market. And even though the Mac is the most intuitive computer in existence today
unless you belong to the De Sade school of software marketing you are going to lay out
for the end user a document describing precisely the problem that your program
solves as well as defining what is appropriate behavior within the program, how to
interpret the output of the program and, finally, how to avoid breaking the program.
To summarize, this User Manual defines the program and makes one helluva good first
design document.
The two exceptions are hacks that are so trivial that they require no
documentation and at the other extreme I can envision serious programs with extensive
context sensitive help sub systems, online tutorials etc. for which no User Manual is
required. In the first case the program is probably simple enough to skip any formal
design and in the second case my advice goes double. If your documentation is going to
be online then then it is e specially important that you write it before you attack the
code.
Putting our own advice to work let's write a User's Manual for our Towers of
Hanoi program. I am sure it is obvious to everyone that the style and literary merits
of this front-end User Manual are practically meaningless and that the polish can be
applied after the program is completed.
User's Manual
Towers of Hanoi
Problem:
1) MacTutor needs a good example of Modula-2 code for the Apple Macintosh
featuring elements of the Mac 'face and the toolbox calls.
2) The world is a bit boring and we could use a nice little game to liven up the day.
Solution:
The Towers of Hanoi a 1,000 year old puzzle with an automatic solution option.
This User's Manual assumes the user is familiar with the fundamentals of the
Macintosh user interface such as clicking, opening icons, dragging etc.
Open the icon entitled "Towers.LOD" by double clicking or using the Open option
in the File menu. Shortly you will see the playing screen of Towers. At the top is a
menu bar with one entry, "Start". Below the menu bar you will see the puzzle
paraphenalia which consists of a horizontal base and three vertical posts.
Pull down the "Start" menu ... you will see three menu options. The options are
"# disks...", "Manual", "Auto...". To start the puzzle select the menu option "#
disks...". A dialog box will appear consisting of seven Radio buttons labelled 3, 4, 5, 6,
7, 8, 9 and a OK box. Using the mouse select the number of disks you wish to play
with. When you have selected the number of disks click in the OK box. The selected
number of disks will then appear on the screen.
Chosing the Style of Play
The second decision you must make is whether to play a manual game or let the
computer play an automatic game. If you select "Manual" then the computer expects
you to move the disks manually using the mouse according to the rules of the puzzle.
The rules of the puzzle are simple enough, you may move the top disk on any post to
any other post so long as at no time is a larger disk on top of a smaller disk. You have
completed the puzzle when all the disks have been moved to the post on the far right of
your screen. To move a disk simply click on the post you wish to move from then click
on the post you wish to move to. Should you violate the rule about larger disks being on
top of smaller disks an alert box will notify you and cancel your move.
Setting the Speed of Play
If you choose the "Auto..." option a dialog box will appear asking you to select the
speed of the solution, 1 is slowest and 9 is fastest. After the program completes you
will be ready to start again.
And now, back to our sponser...
This month I was unable to provide any useful code because of time constraints so
instead I thought I would point you in the direction of where you can find out more
about the language Modula-2. An excellent little volume (145 pages) describing in
loving detail the differences between Modula-2 and Pascal has recently been published
by Springer-Verlag. This book is Modula-2 for Pascal Programmers by Richard
Gleaves. With over 100 examples, a glossary, full syntax diagrams, a thorough index
and table of contents this jewel will bring any Pascal programmer up to speed in
Modula-2 in a very short time.