chapter2.tex 61 KB
Newer Older
lesto's avatar
lesto committed
1 2 3 4 5 6 7 8
%% Thinking Forth
%% Copyright (C) 2004 Leo Brodie
%% Initial transcription by Andrew Nicholson, based on OCR output
%% provided by John Hogerhuis
%%

%Page 037 in first edition

9
%\chapternum{TWO}
10
\chapter{Analysis}\Chapmark{2}
lesto's avatar
lesto committed
11 12 13

%Page 038 in first edition

paysan's avatar
paysan committed
14
\initialb Anyone who tells you there is some definite number of phases to the
lesto's avatar
lesto committed
15 16
software development cycle is a fool.

paysan's avatar
paysan committed
17
Nevertheless \dots{}
lesto's avatar
lesto committed
18

lesto's avatar
lesto committed
19
\section{The Nine Phases of the Programming Cycle}%
lesto's avatar
lesto committed
20

21
As we've seen, \Forth{} integrates aspects of design with aspects of
lesto's avatar
lesto committed
22 23 24 25 26 27
implementation and maintenance. As a result, the notion of a ``typical
development cycle'' makes as much sense as a ``typical noise.''

But any approach is better than no approach, and indeed, some
approaches have worked out better than others. Here is a development
cycle that represents an ``average'' of the most successful approaches
28
used in software projects:%
lesto's avatar
lesto committed
29
\index{P!Programming cycle:!phases|(}
lesto's avatar
lesto committed
30
\begin{description}
lesto's avatar
lesto committed
31
\item[Analysis] \hfill\index{A!Analysis}
lesto's avatar
lesto committed
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
    \begin{enumerate}
    \item Discover the Requirements and Constraints
    \item Build a Conceptual Model of the Solution
    \item Estimate Cost/Schedule/Performance
    \end{enumerate}
\item[Engineering] \hfill
    \begin{enumerate}
    \setcounter{enumi}{3}
    \item Preliminary Design
    \item Detailed Design
    \item Implementation
    \end{enumerate}
\item[Usage] \hfill
    \begin{enumerate}
    \setcounter{enumi}{6}
    \item Optimization
    \item Validation and Debugging
    \item Maintenance
    \end{enumerate}
lesto's avatar
lesto committed
51
\end{description}
52
In this book we'll treat the first six stages of the cycle,
lesto's avatar
lesto committed
53 54
focusing on analysis, design, and implementation.

55
In a \Forth{} project the phases occur on several levels. Looking at a
lesto's avatar
lesto committed
56 57 58 59 60
project from the widest perspective, each of these steps could take a
month or more.  One step follows the next, like seasons.

%Page 039 in first edition

61
But \Forth{} programmers also apply these same phases toward
62
defining each word. The cycle then repeats on the order of minutes.%
lesto's avatar
lesto committed
63
\index{P!Programming cycle:!phases|)}
lesto's avatar
lesto committed
64 65 66 67

Developing an application with this rapid repetition of the
programming cycle is known as using the ``Iterative Approach.''

68 69
\section{The Iterative Approach}%
\index{I!Iterative approach|(}%
lesto's avatar
lesto committed
70
\index{P!Programming cycle:!iterative approach|(}
lesto's avatar
lesto committed
71

lesto's avatar
lesto committed
72 73 74
The iterative approach was explained eloquently by
\person{Kim Harris} \cite{harris81}. \index{H!Harris, Kim|(}
He begins by describing the scientific method:
lesto's avatar
lesto committed
75

76
\begin{tfquot}
77 78 79 80 81 82 83 84
\dots{} a never-ending cycle of discovery and refinement. It first
studies a natural system and gathers observations about its behavior.
Then the observations are modeled to produce a theory about the
natural system. Next, analysis tools are applied to the model, which
produces predictions about the real system's behavior. Experiments
are devised to compare actual behavior to the predicted behavior. The
natural system is again studied, and the model is revised.

lesto's avatar
lesto committed
85 86
\wepsfigb{fig2-1}{The iterative approach to the
software development cycle, from ``The \Forth{} Philosophy,''
87
by \person{Kim Harris}, \emph{Dr.\@ Dobb's Journal.}}%
lesto's avatar
lesto committed
88 89 90 91
\index{H!Harris, Kim|)}

The \emph{goal} of the method is to produce a model which accurately
predicts all observable behavior of the natural system.
92
\end{tfquot}
lesto's avatar
lesto committed
93 94
\person{Harris} then applies the scientific method to the software
development cycle, illustrated in \Fig{fig2-1}:
lesto's avatar
lesto committed
95 96

\begin{enumerate}
lesto's avatar
lesto committed
97 98
\item A problem is analyzed to determine what functions are required
in the solution.
99 100
\item Decisions are made about how to achieve those functions with
the available resources.
lesto's avatar
lesto committed
101
\item A program is written which attempts to implement the design.
lesto's avatar
lesto committed
102 103
\item The program is tested to determine if the functions were
implemented correctly.
lesto's avatar
lesto committed
104 105
\end{enumerate}
%Page 040 in first edition
paysan's avatar
paysan committed
106
Mr. \person{Harris} adds:
lesto's avatar
lesto committed
107

108
\begin{tfquot}
lesto's avatar
lesto committed
109 110 111 112 113
Software development in \Forth{} seeks first to find the simplest
solution to a given problem. This is done by implementing selected
parts of the problem separately and by ignoring as many constraints as
possible. Then one or a few constraints are imposed and the program is
modified.
114
\end{tfquot}
115
An excellent testimonial to the development/testing model of design is
lesto's avatar
lesto committed
116 117 118 119 120 121
evolution. From protozoa to tadpoles to people, each species along the
way has consisted of functional, living beings. The Creator does not
appear to be a top-down designer.

\begin{tip}
Start simple. Get it running. Learn what you're trying to do. Add
122 123
complexity gradually, as needed to fit the requirements and
constraints. Don't be afraid to restart from scratch.
124 125
\end{tip}%
\index{I!Iterative approach|)}%
lesto's avatar
lesto committed
126
\index{P!Programming cycle:!iterative approach|)}
lesto's avatar
lesto committed
127

128 129
\section{The Value of Planning}%
\index{P!Planning:!value of|(}%
lesto's avatar
lesto committed
130
\index{P!Programming cycle:!value of planning|(}
lesto's avatar
lesto committed
131

132
In the nine phases at the start of this chapter we listed five steps
133
\emph{before} ``implementation.'' Yet in \Chap{1} we saw that an
134
overindulgence in planning is both difficult and pointless.
lesto's avatar
lesto committed
135 136 137

Clearly you can't undertake a significant software
project---regardless of the language---without some degree of planning.
138
Exactly what degree is appropriate?%
lesto's avatar
lesto committed
139 140 141
\index{J!Johnson, Dave|(}
\begin{interview}
\noindent More than one \Forth{} programmer has expressed high regard for
lesto's avatar
lesto committed
142 143 144 145
\person{Dave Johnson}'s meticulous approach to planning. \person{Johnson}
is supervisor at Moore Products Co. in Springhouse, Pennsylvania. The firm
specializes in industrial instrumentation and process control
applications. Dave has been using \Forth{} since 1978.
lesto's avatar
lesto committed
146 147

He describes his approach:
148
\begin{tfquot}
149
Compared with many others that use \Forth{}, I suppose we take a more
lesto's avatar
lesto committed
150 151
formal approach. I learned this the hard way, though. My lack of
discipline in the early years has come back to haunt me.
lesto's avatar
lesto committed
152

153
We use two tools to come up with new products: a functional specification
lesto's avatar
lesto committed
154 155 156
and a design specification. Our department of Sales \& Applications comes
up with the functional specification, through customer contact.

lesto's avatar
lesto committed
157 158 159
Once we've agreed on what we're going to do, the functional
specification is turned over to our department. At that point we work
through a design, and come up with the design specification.
lesto's avatar
lesto committed
160

161
Up to this point our approach is no different from programming in any
lesto's avatar
lesto committed
162 163 164 165
language. But with \Forth{}, we go about designing somewhat
differently.  With \Forth{} you don't have to work 95\% through your
design before you can start coding, but rather 60\% before you can get
into the iterative process.
lesto's avatar
lesto committed
166 167 168

%Page 041 in first edition

169 170 171 172 173 174 175 176 177 178 179 180
A typical project would be to add a functional enhancement to one of
our products. For example, we have an intelligent terminal with disk
drives, and we need certain protocols for communicating with another
device. The project to design the protocols, come up with displays,
provide the operator interfaces, etc. may take several months. The
functional specification takes a month; the design specification takes
a month; coding takes three months; integration and testing take
another month.

This is the typical cycle. One project took almost two years, but six
or seven months is reasonable.

181
When we started with \Forth{} five years ago, it wasn't like that. When I
182 183 184 185 186 187
received a functional specification, I just started coding. I used a
cross between top-down and bottom-up, generally defining a structure,
and as I needed it, some of the lower level, and then returning with
more structure.

The reason for that approach was the tremendous pressure to show
lesto's avatar
lesto committed
188 189
something to management. We wound up never writing down what we were
doing. Three years later we would go back and try to modify the code,
190
without any documentation. \Forth{} became a disadvantage because it
191 192 193
allowed us to go in too early. It was fun to make the lights flash and
disk drives hum. But we didn't go through the nitty-gritty design
work. As I said, our ``free spirits'' have come back to haunt us.
lesto's avatar
lesto committed
194

195
Now for the new programmers, we have an established requirement: a
196
thorough design spec that defines in detail all the high-level \Forth{}
197 198 199
words---the tasks that your project is going to do. No more reading a
few pages of the functional specification, answering that, reading a
few more, answering that, etc.
lesto's avatar
lesto committed
200

lesto's avatar
lesto committed
201 202 203
No living programmer likes to document. By ensuring the design ahead
of time, we're able to look back several years later and remember what
we did.
lesto's avatar
lesto committed
204

205 206 207
I should mention that during the design phase there is some amount of
coding done to test out certain ideas. But this code may not be part
of the finished product. The idea is to map out your design.
lesto's avatar
lesto committed
208
\end{tfquot}%
lesto's avatar
lesto committed
209
\index{J!Johnson, Dave|)}
lesto's avatar
lesto committed
210 211 212 213 214
\end{interview}
\person{Johnson} advises us to complete the design specification
before starting to code, with the exception of needed preliminary
tests. The next interview backs up this point, and adds some
additional reasons.%
215
\begin{interview}
lesto's avatar
lesto committed
216 217 218 219 220 221
\index{T!Teleska, John|(}
\noindent \person{John Teleska} has been an independent software
consultant since 1976, specializing in custom applications for
academic research environments.  He enjoys providing research tools
``right at the edge of what technology is able to do.''
\person{Teleska} works in Rochester, New York:
lesto's avatar
lesto committed
222

223
\begin{tfquot}
224
I see the software development process as having two phases. The first is
lesto's avatar
lesto committed
225 226 227
making sure I understand what the problem is. The second is
implementation, including debugging, verification, etc.

228 229 230 231 232 233
My goal in Phase One is an operational specification. I start with a
problem description, and as I proceed it becomes the operational
specification. My understanding of the problem metamorphoses into a
solution. The better the understanding, the more complete the
solution. I look for closure; a sense of having no more questions that
aren't answered in print.
lesto's avatar
lesto committed
234

235 236 237
I've found that on each project I've been putting more time into Phase
One, much to the initial dismay of many of my clients. The limiting
factor is how
lesto's avatar
lesto committed
238
%Page 042 in first edition
239 240 241 242 243
much I can convince the client it's necessary to spend that time up
front.  Customers generally don't know the specifications for the job
they want done. And they don't have the capital---or don't feel they
do---to spend on good specs. Part of my job is to convince them it
will end up costing more time and money not to.
lesto's avatar
lesto committed
244

245
Some of Phase One is spent on feasibility studies. Writing the spec
lesto's avatar
lesto committed
246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
unearths uncertainties. I try to be as uncertain about uncertainties
as possible. For instance, they may want to collect 200,000 samples a
second to a certain accuracy. I first need to find out if it's even
possible with the equipment they've got. In this case I've got to test
its feasibility by writing a patch of code.

Another reason for the spec is to cover myself. In case the
application performs to the spec but doesn't fully satisfy the
customer, it's the customer's responsibility. If the customer wants
more, we'll have to renegotiate. But I see it as the designer's
responsibility to do whatever is necessary to generate an operational
specification that will do the job to the customer's satisfaction.

I think there are consultants who bow to client pressure and limit the
time they spend on specs, for fear of losing the job. But in these
situations nobody ends up happy.
262
\end{tfquot}
lesto's avatar
lesto committed
263
\index{T!Teleska, John|)}
264 265 266
\end{interview}%
We'll return to the \person{Teleska} interview momentarily.%
\index{P!Planning:!value of|)}%
lesto's avatar
lesto committed
267
\index{P!Programming cycle:!value of planning|)}
lesto's avatar
lesto committed
268

269 270
\section{The Limitations of Planning}%
\index{P!Planning:!limitations of|(}%
lesto's avatar
lesto committed
271
\index{P!Programming cycle:!limitations of planning|(}
lesto's avatar
lesto committed
272

273
Experience has taught us to map out where we're going before we begin
lesto's avatar
lesto committed
274
coding. But planning has certain limitations. The following interviews
275
give different perspectives to the value of planning.%
276
\begin{interview}
lesto's avatar
lesto committed
277
\index{T!Teleska, John|(}
lesto's avatar
lesto committed
278 279 280
\noindent Despite \person{Teleska}'s preference for a well-planned
project, he suggests that the choice between a top-down and bottom-up
approach may depend on the situation:
lesto's avatar
lesto committed
281

282
\begin{tfquot}
lesto's avatar
lesto committed
283 284 285 286 287 288 289 290
On two recent projects involving a lot of technical interface work, I
did the whole thing bottom-up. I milled around in a bunch of
data-sheets and technical descriptions of little crannies of the
operating system I was dealing with. I felt lost most of the time,
wondering why I ever took the job on.  Then finally I reached a
critical mass of some sort and began putting small programs together
that made small things happen. I continued, bottom-up, until I matched
the target application.
lesto's avatar
lesto committed
291

292
My top-down sense was appalled at this procedure. But I've seen me go
lesto's avatar
lesto committed
293 294 295 296 297
through this process successfully too many times to discount it for
any pedagogical reasons. And there is always this difficult phase
which it seems no amount of linear thinking will penetrate.
Programming seems a lot more intuitive than we, in this business, tell
each other it ought to be.
lesto's avatar
lesto committed
298

299
I think if the application elicits this sense of being lost, I proceed
lesto's avatar
lesto committed
300 301
bottom-up. If the application is in familiar territory then I'll
probably use a more traditional by-the-book approach.
302
\end{tfquot}
lesto's avatar
lesto committed
303 304
\index{T!Teleska, John|)}
\end{interview}
lesto's avatar
lesto committed
305 306 307

%Page 043 in first edition

308
\noindent And here's another view:%
paysan's avatar
paysan committed
309
\index{S!Starling, Michael|(}
310
\begin{interview}
311
\noindent At the time I interviewed him, \person{Michael Starling} of Union
lesto's avatar
lesto committed
312 313
Carbide was putting the final touches on two applications involving
user-configurable laboratory automation and process control automation
314
systems. For the pilot plant system, \person{Starling} designed both the
lesto's avatar
lesto committed
315 316 317 318 319
hardware and software to known requirements; on the laboratory
automation system he also defined the requirements himself.

His efforts were extremely successful. On one project, the new system
typically costs only 20\% as much as the equivalent system and
lesto's avatar
lesto committed
320 321 322 323
requires days, instead of months, to install and configure.

I asked him what techniques of project management he employed.

324
\begin{tfquot}
325
On both of these projects much design was needed. I did not follow the
lesto's avatar
lesto committed
326 327
traditional analysis methods, however. I did employ these steps:

328
First, I clearly defined the boundaries of the problem.
lesto's avatar
lesto committed
329

330
Second, I determined what the smaller functional pieces, the software
lesto's avatar
lesto committed
331 332
subsystems, had to be.

333
Third, I did each piece, put them together, and the system ran.
lesto's avatar
lesto committed
334

lesto's avatar
lesto committed
335 336 337
Next, I asked the users ``Does this meet your requirements?''
Sometimes it didn't, and in ways that neither the users nor the
specification designers could have anticipated.
lesto's avatar
lesto committed
338

339
For instance, the designers didn't realize that the original
lesto's avatar
lesto committed
340 341 342 343 344
specification wouldn't produce pleasing, human-oriented graphics
displays. After working with the interactive graphics on the first
version, users were applying arbitrary scales and coming up with
oddball displays.

345
So even after the basic plot algorithm was designed, we realized we
lesto's avatar
lesto committed
346 347 348 349
needed auto-scaling. We went back in and analyzed how human beings
plot data and wrote a first level plot function that evaluates the x
and y data and how much will fit on the graph.

350
After that, we realized that not all the data taken will be of
lesto's avatar
lesto committed
351 352
interest to experimenters. So we added a zoom capability.

353
This iterative approach resulted in cleaner code and better thought
lesto's avatar
lesto committed
354 355 356 357 358
out code. We established a baseline set of goals and built a minimal
system to the users' known requirements. Then we'd crank in the
programmer's experience to improve it and determine what the users
forgot they needed when they generated the specs.

359
The users did not invent most of the new ideas. The programmers did,
lesto's avatar
lesto committed
360 361 362 363 364
and they would bounce these ideas off the users. The problem
definition was a two-way street. In some cases they got things they
didn't know they could do on such a small computer, such as applying
digital filters and signal processing to the data.

365
One of the things about \Forth{} that makes this approach possible is
lesto's avatar
lesto committed
366
that primitives are easily testable. It takes some experience with
367
\Forth{} to learn how to take advantage of this. Guys from traditional
lesto's avatar
lesto committed
368 369 370
environments want to write ten pages of code at their desk, then sit
down to type it in and expect it to work.

371
To summarize my approach: I try to find out from the users what they
lesto's avatar
lesto committed
372 373
need, but at the same time recognizing its incompleteness. Then I keep
%Page 044 in first edition
lesto's avatar
lesto committed
374 375 376 377 378 379 380 381
them involved in the design during the implementation, since they have
the expertise in the application.  When they see the result, they feel
good because they know their ideas were involved.

The iterative approach places highest value on producing a good
solution to the real problem. It may not always give you the most
predictable software costs. The route to a solution may depend upon
your priorities. Remember:
382
\begin{list}{}{}
lesto's avatar
lesto committed
383 384 385
\item Good
\item Fast
\item Cheap
386 387
\end{list}
Pick any two!
388
\end{tfquot}
389
\end{interview}
lesto's avatar
lesto committed
390

lesto's avatar
lesto committed
391 392 393
\noindent As \person{Starling} observes, you don't know completely what
you're doing till you've done it once. In my own experience, the best way
to write an application is to write it twice. Throw away the first
394
version and chalk it up to experience.%
paysan's avatar
paysan committed
395
\index{S!Starling, Michael|)}%
lesto's avatar
lesto committed
396
\index{K!Kogge, Peter|(}
397
\begin{interview}
lesto's avatar
lesto committed
398 399
\noindent \person{Peter Kogge} is Senior Technical Staff in the IBM
Federal Systems Division, Oswego, New York:
lesto's avatar
lesto committed
400

401
\begin{tfquot}
lesto's avatar
lesto committed
402 403
One of the key advantages I find in \Forth{} is that it allows me to
very quickly prototype an application without all the bells and
404 405 406 407 408 409 410
whistles, and often with significant limitations, but enough to wring
out the ``human interface'' by hands-on trial runs.

When I build such a prototype, I do so with the firm constraint that I
will use not a single line of code from the prototype in the final
program. This enforced ``do-over'' almost always results in far
simpler and more elegant final programs, even when those programs are
411
written in something other than \Forth{}.
412
\end{tfquot}
413
\end{interview}%
lesto's avatar
lesto committed
414
\index{K!Kogge, Peter|)}
lesto's avatar
lesto committed
415

lesto's avatar
lesto committed
416 417 418
\noindent Our conclusions? In the \Forth{} environment planning is
necessary. But it should be kept short. Testing and prototyping are
the best ways to discover what is really needed.
lesto's avatar
lesto committed
419 420

A word of caution to project managers: If you're supervising any
421
experienced \Forth{} programmers, you won't have to worry about them
lesto's avatar
lesto committed
422 423 424 425
spending too much time on planning. Thus the following tip has two
versions:

\begin{tip}
426
For newcomers to \Forth{} (with ``traditional'' backgrounds):
427
Keep the analysis phase to a minimum.
lesto's avatar
lesto committed
428

paysan's avatar
paysan committed
429
\medskip
430
For \Forth{} addicts (without a ``traditional'' background):
431
Hold off on coding as long as you can possibly stand it.
lesto's avatar
lesto committed
432 433
\end{tip}
%Page 045 in first edition
434
Or, as we observed in \Chap{1}:
lesto's avatar
lesto committed
435 436 437 438

\begin{tip}
Plan for change (by designing components that can be changed).
\end{tip}
439
Or, simply:
lesto's avatar
lesto committed
440 441 442

\begin{tip}
Prototype.
443 444
\end{tip}%
\index{P!Planning:!limitations of|)}%
lesto's avatar
lesto committed
445
\index{P!Programming cycle:!limitations of planning|)}
lesto's avatar
lesto committed
446

447 448
\section{The Analysis Phase}%
\index{A!Analysis|(}%
lesto's avatar
lesto committed
449

450
In the remainder of this chapter we'll discuss the analysis phase.
lesto's avatar
lesto committed
451
Analysis is an organized way of understanding and documenting what
452
the program should do.%
lesto's avatar
lesto committed
453
\index{A!Analysis!defined}
lesto's avatar
lesto committed
454 455 456 457

With a simple program that you write for yourself in less than an
hour, the analysis phase may take about 250 microseconds. At the other
extreme, some projects will take many man-years to build. On such a
lesto's avatar
lesto committed
458 459
project, the analysis phase is critical to the success of the entire
project.
lesto's avatar
lesto committed
460 461 462

We've indicated three parts to the analysis phase:

lesto's avatar
lesto committed
463
\begin{enumerate}\parsep=0pt\itemsep=0pt
lesto's avatar
lesto committed
464 465 466 467 468 469 470
\item Discovering the requirements and constraints
\item Building a conceptual model of the solution
\item Estimating cost, scheduling, and performance
\end{enumerate}

\noindent Let's briefly describe each part:

471 472
\subsection{Discovering the Requirements}%
\index{A!Analysis!requirements|(}%
lesto's avatar
lesto committed
473
\index{R!Requirements|(}
lesto's avatar
lesto committed
474

lesto's avatar
lesto committed
475 476 477 478
The first step is to determine what the application should do. The
customer, or whoever wants the system, should supply a ``requirements
specification.'' This is a modest document that lists the minimum
capabilities for the finished product.
lesto's avatar
lesto committed
479 480

The analyst may also probe further by conducting interviews and
481 482
sending out questionnaires to the users.%
\index{A!Analysis!requirements|)}%
lesto's avatar
lesto committed
483
\index{R!Requirements|)}
lesto's avatar
lesto committed
484

485 486
\subsection{Discovering the Constraints}%
\index{A!Analysis!constraints|(}%
lesto's avatar
lesto committed
487
\index{C!Constraints|(}
lesto's avatar
lesto committed
488

489
The next step is to discover any limiting factors. How important is
lesto's avatar
lesto committed
490 491
speed? How much memory is available? How soon do you need it?

492 493
No matter how sophisticated our technology becomes, programmers will
always be bucking limitations. System capacities inexplicably
lesto's avatar
lesto committed
494 495
%Page 046 in first edition
diminish over time. The double-density disk drives that once were the
496 497 498 499
answer to my storage prayers no longer fill the bill. The
double-sided, double-density drives I'll get next will seem like a
vast frontier---for a while. I've heard guys with 10-megabyte hard
disks complain of feeling cramped.
lesto's avatar
lesto committed
500 501 502 503 504

Whenever there's a shortage of something---and there always will
be---tradeoffs have to be made. It's best to use the analysis phase to
anticipate most limitations and decide which tradeoffs to make.

505
On the other hand, you should \emph{not} consider other types of
lesto's avatar
lesto committed
506 507 508
constraints during analysis, but should instead impose them gradually
during implementation, the way one stirs flour into gravy.

509
The type of constraint to consider during analysis includes those that
paysan's avatar
paysan committed
510
might affect the overall approach. The type to defer includes those
lesto's avatar
lesto committed
511 512 513
that can be handled by making iterative refinements to the planned
software design.

514
As we heard in our earlier interviews, finding out about \emph{hardware}
lesto's avatar
lesto committed
515 516
constraints\index{H!Hardware constraints} often requires writing
some test code and trying things out.
lesto's avatar
lesto committed
517

518
Finding out about the \emph{customer's} constraints%
lesto's avatar
lesto committed
519 520 521
\index{C!Customer constraints}
is usually a matter of asking the customer, or of taking written
surveys. ``How fast do you need such-and-such, on a scale of one to
522 523
ten?'', etc.%
\index{A!Analysis!constraints|)}%
lesto's avatar
lesto committed
524
\index{C!Constraints|)}
lesto's avatar
lesto committed
525

526 527
\subsection{Building a Conceptual Model of the Solution}%
\index{A!Analysis!conceptual model|(}%
lesto's avatar
lesto committed
528
\index{C!Conceptual model|(}
lesto's avatar
lesto committed
529

530 531
A conceptual model is an imaginary solution to the problem. It is a
view of how the system \emph{appears} to work. It is an answer to all
532
the requirements and constraints.%
lesto's avatar
lesto committed
533
\index{C!Conceptual model!defined}
534 535 536

\wepsfigp{img2-047}{Refining the conceptual model to meet
requirements and constraints.}
lesto's avatar
lesto committed
537 538

If the requirements definition is for ``something to stand on to paint
539 540 541 542 543
the ceiling,'' then a description of the conceptual model is ``a
device that is free-standing (so you can paint the center of the
room), with several steps spaced at convenient intervals (so you can
climb up and down), and having a small shelf near the top (to hold
your paint can).''
lesto's avatar
lesto committed
544

545 546 547
A conceptual model is not quite a design, however. A design begins to
describe how the system \emph{really} works. In design, the image of a
step ladder would begin to emerge.
lesto's avatar
lesto committed
548

549
\Forth{} blurs the distinction a little, because all definitions are
lesto's avatar
lesto committed
550
written in conceptual terms, using the lexicons of lower level
551
components. In fact, later in this chapter we'll use \Forth{}
552
``pseudocode'' to describe conceptual model solutions.
lesto's avatar
lesto committed
553

554 555
Nevertheless, it's useful to make the distinction. A conceptual model
is more flexible than a design. It's easier to fit the requirements
lesto's avatar
lesto committed
556 557 558 559 560 561 562
and constraints into the model than into a design.

\begin{tip}
Strive to build a solid conceptual model before beginning the design.
\end{tip}

%Page 047 in first edition
563
%img2-47 moved forward
lesto's avatar
lesto committed
564 565
%Page 048 in first edition

lesto's avatar
lesto committed
566 567 568
\noindent Analysis consists of expanding the requirements definition
into a conceptual model. The technique involves two-way communication
with the customer in successive attempts to describe the model.
lesto's avatar
lesto committed
569

paysan's avatar
paysan committed
570
Like the entire development cycle, the analysis phase is best approached
lesto's avatar
lesto committed
571 572
iteratively. Each new requirement will tend to suggest something in
your mental model. Your job is to juggle all the requirements and
lesto's avatar
lesto committed
573 574
constraints until you can weave a pattern that fits the bill.

paysan's avatar
paysan committed
575
\wepsfigb{fig2-2}{An iterative approach to analysis.}
lesto's avatar
lesto committed
576

lesto's avatar
lesto committed
577 578 579
\Fig{fig2-2} illustrates the iterative approach to the analysis phase.
The final step is one of the most important: show the documented model
to the customer. Use whatever means of communication are
lesto's avatar
lesto committed
580 581 582
necessary---diagrams, tables, or cartoons---to convey your
understanding to the customer and get the needed feedback. Even if you
cycle through this loop a hundred times, it's worth the effort.
583

lesto's avatar
lesto committed
584 585 586
In the next three sections we'll explore three techniques for defining
and documenting the conceptual model:

lesto's avatar
lesto committed
587
\begin{enumerate}
lesto's avatar
lesto committed
588 589 590
\item defining the interfaces
\item defining the rules
\item defining the data structures.
591
\end{enumerate}%
lesto's avatar
lesto committed
592
\index{A!Analysis|)}
lesto's avatar
lesto committed
593

594 595 596
\section{Defining the Interfaces}%
\index{A!Analysis!interface definition|(}%
\index{C!Conceptual model!interface definition|(}%
lesto's avatar
lesto committed
597
\index{I!Interface definition|(}
lesto's avatar
lesto committed
598 599 600

\begin{tip}
First, and most importantly, the conceptual model should describe the
lesto's avatar
lesto committed
601
system's interfaces.\index{I!Interface definition}
602
\end{tip}%
603
\begin{interview}
lesto's avatar
lesto committed
604
\index{T!Teleska, John|(}
605
\person{Teleska}:
lesto's avatar
lesto committed
606

607
\begin{tfquot}
608
The ``spec'' basically deals with WHAT. In its most glorious form, it
lesto's avatar
lesto committed
609 610 611
describes what the system would look like to the user---you might call it
the user's manual. I find I write more notes on the human
interaction---what it
lesto's avatar
lesto committed
612
%Page 049 in first edition
lesto's avatar
lesto committed
613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635
will look like on the outside---than on the part that gets the job
done. For instance, I'll include a whole error-action listing to show
what happens when a particular error occurs. Oddly, this is the part
that takes the most time to implement anyway.

I'm currently working on a solid-state industrial washing-machine
timer. In this case, the user interface is not that complex. What is
complex is the interface to the washing machine, for which I must
depend on the customer and the documentation they can provide.

The significant interface is whatever is the arms and legs of the
product. I don't make the distinction between hardware and software at
this early stage. They can be interchanged in the implementation.

The process of designing hardware and the process of designing
software are analogous. The way I design hardware is to treat it as a
black box. The front panel is input and output. You can do the same
with software.

I use any techniques, diagrams, etc., to show the customer what the
inputs and outputs look like, using his description of what the
product has to do.  But in parallel, in my own mind, I'm imagining how
it will be implemented.  I'm evaluating whether I can do this
lesto's avatar
lesto committed
636
efficiently. So to me it's not a black box, it's a gray box. The
lesto's avatar
lesto committed
637
designer must be able to see inside the black boxes.
lesto's avatar
lesto committed
638 639

When I design a system that's got different modules, I try to make the
lesto's avatar
lesto committed
640 641
coupling as rational and as little as possible. But there's always
give and take, since you're compromising the ideal.
lesto's avatar
lesto committed
642

lesto's avatar
lesto committed
643
\index{D!Data-flow diagrams|(}
lesto's avatar
lesto committed
644
For the document itself, I use DFDs {[}data-flow diagrams, which we'll
lesto's avatar
lesto committed
645 646 647 648 649
discuss later{]}, and any other kind of representation that I can show
to my client. I show them as many diagrams as I can to clarify my
understanding.  I don't generally use these once it comes to
implementation. The prose must be complete, even without reference to
the diagrams.
lesto's avatar
lesto committed
650 651
\end{tfquot}%
\index{T!Teleska, John|)}
652
\end{interview}%
lesto's avatar
lesto committed
653
\index{E!Error handling|(}
lesto's avatar
lesto committed
654
\begin{tip}
655
Decide on error- and exception-handling early as part of defining the
lesto's avatar
lesto committed
656 657 658
interface.
\end{tip}

659 660 661 662 663 664
\noindent It's true that when coding for oneself, a programmer can
often concentrate first on making the code run correctly under
\emph{normal} conditions, then worry about error-handling later. When
working for someone else, however, error-handling should be worked out
ahead of time. This is an area often overlooked by the beginning
programmer.
lesto's avatar
lesto committed
665

666 667
The reason it's so important to decide on error-handling at this stage
is the wide divergence in how errors can be treated. An error might be:
lesto's avatar
lesto committed
668 669 670

\begin{itemize}
\item ignored
lesto's avatar
lesto committed
671 672
\item made to set a flag indicating that an error occurred, while
processing continues
lesto's avatar
lesto committed
673
\item made to halt the application immediately
lesto's avatar
lesto committed
674 675
\item designed to initiate procedures to correct the problem and keep
the program running.
lesto's avatar
lesto committed
676
\end{itemize}
paysan's avatar
paysan committed
677
%
lesto's avatar
lesto committed
678
%Page 050 in first edition
paysan's avatar
paysan committed
679
%
lesto's avatar
lesto committed
680
There's room for a serious communications gap if the degree of
lesto's avatar
lesto committed
681 682
complexity required in the error-handling is not nailed down early.
Obviously, the choice bears tremendous impact on the design and
683
implementation of the application.%
lesto's avatar
lesto committed
684
\index{E!Error handling|)}
lesto's avatar
lesto committed
685 686 687 688

\begin{tip}
Develop the conceptual model by imagining the data traveling through and
being acted upon by the parts of the model.
689
\end{tip}%
paysan's avatar
paysan committed
690
\index{S!Structured analysis|(}
lesto's avatar
lesto committed
691 692 693
A discipline called \emph{structured analysis} \cite{weinberg80}
offers some techniques for describing interfaces in ways that your
clients will easily understand.  One of these techniques is called the
694
``data-flow diagram'' (DFD), which \person{Teleska} mentioned.
lesto's avatar
lesto committed
695

lesto's avatar
lesto committed
696
\wepsfiga{fig2-3}{A data-flow diagram.}
lesto's avatar
lesto committed
697 698

A data-flow diagram, such as the one depicted in \Fig{fig2-3},
699 700 701 702
emphasizes what happens to items of data as they travel through the
system.  The circles represent ``transforms,'' functions that act upon
information.  The arrows represent the inputs and outputs of the
transforms.
lesto's avatar
lesto committed
703 704 705 706 707 708 709 710 711 712 713 714 715

The diagram depicts a frozen moment of the system in action. It
ignores initialization, looping structures, and other details of
programming that relate to time.

Three benefits are claimed for using DFDs:

First, they speak in simple, direct terms to the customer. If your
%Page 051 in first edition
customer agrees with the contents of your data-flow diagram, you know
you understand the problem.

Second, they let you think in terms of the logical ``whats,'' without
716 717
getting caught up in the procedural ``hows,'' which is consistent with
the philosophy of hiding information as we discussed in the last chapter.
lesto's avatar
lesto committed
718 719 720 721

Third, they focus your attention on the interfaces to the system and
between modules.

722 723 724
\Forth{} programmers, however, rarely use DFDs except for the customer's
benefit. \Forth{} encourages you to think in terms of the conceptual
model, and \Forth{}'s implicit use of a data stack makes the passing of
725
data among modules so simple it can usually be taken for granted.
726 727
This is because \Forth{}, used properly, approaches a functional language.%
\index{D!Data-flow diagrams|)}%
paysan's avatar
paysan committed
728
\index{S!Structured analysis|)}%
lesto's avatar
lesto committed
729
\index{P!Pseudocode|(}
paysan's avatar
paysan committed
730

731
For anyone with a few days' familiarity with \Forth{}, simple definitions
732
convey at least as much meaning as the diagrams:
lesto's avatar
lesto committed
733
\begin{Code}
734 735 736 737 738
: request  ( quantity part# -- )
   on-hand?  IF  transfer  ELSE  reorder  THEN ;
: reorder   authorization?  IF  p.o.  THEN ;
: p.o.   bookkeeping copy   receiving copy
   vendor mail-copy ;
lesto's avatar
lesto committed
739
\end{Code}
740
This is \Forth{} pseudocode. No effort has been made to determine what
lesto's avatar
lesto committed
741 742 743 744 745 746 747 748
values are actually passed on the stack, because that is an
implementation detail. The stack comment for \forth{REQUEST} is used
only to indicate the two items of data needed to initiate the process.

(If I were designing this application, I'd suggest that the user
interface be a word called \forth{NEED}, which has this syntax:

\begin{Code}
749
need 50 axles
lesto's avatar
lesto committed
750 751 752 753 754
\end{Code}

\noindent \forth{NEED} converts the quantity into a numeric value on
the stack, translates the string \forth{AXLES} into a part number,
also on the stack, then calls \forth{REQUEST}. Such a command should
755
be defined only at the outer-most level.)%
756
\begin{interview}
lesto's avatar
lesto committed
757 758 759
\index{J!Johnson, Dave|(}
\person{Johnson} of Moore Products Co. has a few words on \Forth{}
pseudocode:
760
\begin{tfquot}
761
IBM uses a rigorously documented PDL (program design language). We use
762
a PDL here as well, although we call it FDL, for \Forth{} design
763
language. It's probably worthwhile having all those standards, but
764
once you're familiar with \Forth{}, \Forth{} itself can be a design
765 766
language. You just have to leave out the so-called ``noise'' words:
\forth{C@}, \forth{DUP}, \forth{OVER}, etc., and show only the basic
lesto's avatar
lesto committed
767 768
flow. Most \Forth{} people probably do that informally. We do it
purposefully.
769 770
\end{tfquot}%
\index{J!Johnson, Dave|)}%
lesto's avatar
lesto committed
771
\end{interview}%
lesto's avatar
lesto committed
772
\index{P!Pseudocode|)}
lesto's avatar
lesto committed
773
%Page 052 in first edition
paysan's avatar
paysan committed
774
\begin{interview*}
lesto's avatar
lesto committed
775 776 777
During one of our interviews I asked \person{Moore}\index{M!Moore,
Charles|(} if he used diagrams of any sort to plan out the conceptual
model, or did he code straight into \Forth{}? His reply:
lesto's avatar
lesto committed
778

779
\begin{tfquot}
lesto's avatar
lesto committed
780 781
The conceptual model \emph{is} \Forth{}. Over the years I've learned
to think that way.
782
\end{tfquot}
783
Can everyone learn to think that way?
lesto's avatar
lesto committed
784

785
\begin{tfquot}
786
I've got an unfair advantage. I codified my programming style and other
lesto's avatar
lesto committed
787 788 789 790
people have adopted it. I was surprised that this happened. And I feel at a
lovely advantage because it is my style that others are learning to emulate.
Can they learn to think like I think? I imagine so. It's just a matter of
practice, and I've had more practice.
lesto's avatar
lesto committed
791
\end{tfquot}\index{M!Moore, Charles|)}
paysan's avatar
paysan committed
792
\end{interview*}%
793 794
\index{A!Analysis!interface definition|)}%
\index{C!Conceptual model!interface definition|)}%
lesto's avatar
lesto committed
795
\index{I!Interface definition|)}
lesto's avatar
lesto committed
796

797 798 799
\section{Defining the Rules}%
\index{A!Analysis!rule definition|(}%
\index{C!Conceptual model!rule definition|(}%
800
\index{R!Rule definition|(}%
paysan's avatar
paysan committed
801
\program{phone1}
lesto's avatar
lesto committed
802

lesto's avatar
lesto committed
803
Most of your efforts at defining a problem will center on describing
804
the interface.%
lesto's avatar
lesto committed
805
\index{I!Interface definition}
lesto's avatar
lesto committed
806
Some applications will also require that you define the set of
paysan's avatar
paysan committed
807 808 809 810 811
application rules.

All programming involves rules. Usually these rules are so simple it
hardly matters how you express them: ``If someone pushes the button,
ring the bell.''
lesto's avatar
lesto committed
812 813 814 815 816 817

Some applications, however, involve rules so complicated that they
can't be expressed in a few sentences of English. A few formal techniques
can come in handy to help you understand and document these more
complicated rules.

lesto's avatar
lesto committed
818 819 820 821 822
Here's an example. Our requirements call for a system to compute the
charges on long-distance phone calls. Here's the customer's
explanation of its rate structure. (I made this up; I have no idea how
the phone company actually computes their rates except that they
overcharge.)
lesto's avatar
lesto committed
823

824
\begin{tfquot}
825 826 827 828 829 830 831 832 833 834 835
All charges are computed by the minute, according to distance in
hundreds of miles, plus a flat charge. The flat charge for direct dial
calls during weekdays between 8 A.M. and 5 P.M. is .30 for the first
minute, and .20 for each additional minute; in addition, each minute
is charged .12 per 100 miles. The flat charge for direct calls during
weekdays between 5 P.M. and 11 P.M. is .22 for the first minute, and
.15 for each additional minute; the distance rate per minute is .10
per 100 miles. The flat charge for direct calls late during weekdays
between 11 P.M. or anytime on Saturday, Sundays, or holidays is .12
for the first minute, and .09 for each additional minute; the distance
rate per minute is .06 per 100 miles. If the call requires assistance
lesto's avatar
lesto committed
836
from the operator, the flat charge increases by .90, regardless of the hour.
837
\end{tfquot}
838 839 840
This description is written in plain old English, and it's quite a
mouthful.  It's hard to follow and, like an attic cluttered with
accumulated belongings, it may even hide a few bugs.
lesto's avatar
lesto committed
841 842

%Page 053 in first edition
843 844
In building a conceptual model for this system, we must describe the
rate structure in an unambiguous, useful way. The first step towards
lesto's avatar
lesto committed
845
cleaning up the clutter involves factoring out irrelevant pieces of
paysan's avatar
paysan committed
846
information---that is, applying the rules of limited redundancy. We
847
can improve this statement a lot by splitting it into two statements.
848
First there's the time-of-day rule:%
lesto's avatar
lesto committed
849
\index{A!Analysis!conceptual model|)}
lesto's avatar
lesto committed
850

851
\begin{tfquot}
852
Calls during weekdays between 8 A.M. and 5 P.M. are charged at ``full'' rate.
lesto's avatar
lesto committed
853 854 855
Calls during weekdays between 5 P.M. and 11 P.M. are charged at ``lower''
rate. Calls placed during weekdays between 11 P.M. or anytime on Saturday,
Sundays, or holidays are charged at the ``lowest'' rate.
856
\end{tfquot}
857 858 859
Then there's the rate structure itself, which should be described in
terms of ``first-minute rate,'' ``additional minute rate,'' ``distance
rate,'' and ``operator-assistance rate.''
lesto's avatar
lesto committed
860 861 862 863

\begin{tip}
Factor the fruit. (Don't confuse apples with oranges.)
\end{tip}
864 865 866
These prose statements are still difficult to read, however. System
analysts use several techniques to simplify these statements:
structured English, decision trees, and decision tables. Let's study
867
each of these techniques and evaluate their usefulness in the \Forth{}
868
environment.
lesto's avatar
lesto committed
869

870 871
\subsection{Structured English}%
\index{A!Analysis!Structured English|(}%
lesto's avatar
lesto committed
872
\index{S!Structured English|(}
lesto's avatar
lesto committed
873

874
Structured English is a sort of structured pseudocode in which our rate
lesto's avatar
lesto committed
875 876
statement would read something like this:

877
%Page 053/054 in first edition
878
\begin{Code}[baselinestretch=0.95]
lesto's avatar
lesto committed
879 880 881 882 883 884 885 886 887 888 889 890 891 892
IF full rate
   IF direct-dial
      IF first-minute
	 .30 + .12/100miles
      ELSE ( add'l- minute)
	 .20 + .12/100miles
      ENDIF
   ELSE ( operator )
      IF first-minute
	 1.20 + .12/100miles
      ELSE ( add'l- minute)
	 .20 + .12/100miles
      ENDIF
   ENDIF
893
ELSE  ( not-full-rate)
lesto's avatar
lesto committed
894 895 896 897 898 899
   IF lower-rate
      IF direct-dial
	 IF first-minute
	    .22 + .10/100miles
	 ELSE ( add'l- minute)
	    .15 + .10/100miles
900
	 ENDIF
lesto's avatar
lesto committed
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916
      ELSE ( operator)
	 IF first-minute
	    1.12 + .10/100miles
	 ELSE ( add'l- minute)
	    .15 + .10/100miles
	 ENDIF
      ENDIF
   ELSE ( lowest-rate)
      IF direct-dial
	 IF first-minute
	    .12 + .06/100miles
	 ELSE ( add'l- minute)
	    .09 + .O6/100miles
	 ENDIF
      ELSE ( operator)
	 IF first-minute
paysan's avatar
paysan committed
917
	    1.02 + .O6/100miles
lesto's avatar
lesto committed
918 919 920 921 922 923 924
	 ELSE ( add'l- minute)
	    .09 + .06/100miles
	 ENDIF
      ENDIF
   ENDIF
ENDIF
\end{Code}
925 926
This is just plain awkward. It's hard to read, harder to maintain, and
hardest to write. And for all that, it's worthless at implementation
927 928
time. I don't even want to talk about it anymore.%
\index{A!Analysis!Structured English|)}%
lesto's avatar
lesto committed
929
\index{S!Structured English|)}
lesto's avatar
lesto committed
930

931 932
\subsection{The Decision Tree}%
\index{A!Analysis!decision tree|(}%
lesto's avatar
lesto committed
933 934
\index{D!Decision tree|(}

paysan's avatar
paysan committed
935
\wepsfigt{fig2-4}{Example of a decision tree.}
lesto's avatar
lesto committed
936

937 938 939 940
\Fig{fig2-4} illustrates the telephone rate rules by means of a
decision tree.  The decision tree is the easiest method of any to
``follow down'' to determine the result of certain conditions. For
this reason, it may be the best representation to show the customer.
lesto's avatar
lesto committed
941 942

Unfortunately, the decision tree is difficult to ``follow up,'' to
943 944 945
determine which conditions produce certain results. This difficulty
inhibits seeing ways to simplify the problem. The tree obscures the
fact that additional minutes cost the same, whether the operator
946 947
assists or not. You can't see the facts for the tree.%
\index{A!Analysis!decision tree|)}%
lesto's avatar
lesto committed
948
\index{D!Decision tree|)}
lesto's avatar
lesto committed
949 950 951 952 953

%Page 055 in first edition

% Figure 2-4 was here

954 955
\subsection{The Decision Table}%
\index{A!Analysis!decision table|(}%
lesto's avatar
lesto committed
956
\index{D!Decision table|(}
lesto's avatar
lesto committed
957

958
The decision table, described next, provides the most usable graphic
lesto's avatar
lesto committed
959 960 961 962
representation of compound rules for the programmer, and possibly for
the customer as well. \Fig{fig2-5} shows our rate structure rules in
decision-table form.

paysan's avatar
paysan committed
963
\wepsfigt{fig2-5}{The decision table.}
lesto's avatar
lesto committed
964 965 966 967

In \Fig{fig2-5} there are three dimensions: the rate discount, whether
an operator intervenes, and initial minute vs. additional minute.

968 969
Drawing problems with more than two dimensions gets a little tricky.
As you can see, these additional dimensions can be depicted on
lesto's avatar
lesto committed
970 971
%Page 056 in first edition
paper as subdimensions within an outer dimension. All of the
972 973 974
subdimension's conditions appear within every condition of the outer
dimension.  In software, any number of dimensions can be easily
handled, as we'll see.
lesto's avatar
lesto committed
975 976

All the techniques we've described force you to analyze which
977 978
conditions apply to which dimensions. In factoring these dimensions,
two rules apply:
lesto's avatar
lesto committed
979

980 981 982
First, all the elements of each dimension must be mutually exclusive.
You don't put ``first minute'' in the same dimension as ``direct
dial,'' because they are not mutually exclusive.
lesto's avatar
lesto committed
983

984 985
Second, all possibilities must be accounted for within each dimension.
If there were another rate for calls made between 2 A.M. to 2:05 A.M.,
lesto's avatar
lesto committed
986 987
the table would have to be enlarged.

988 989
But our decision tables have other advantages all to themselves.  The
decision table not only reads well to the client but actually benefits
lesto's avatar
lesto committed
990 991 992
the implementor in several ways:

\begin{description}
lesto's avatar
lesto committed
993 994 995
\item[Transferability to actual code.] This is particularly true in
\Forth{}, where decision tables are easy to implement in a form very
similar to the drawing.
lesto's avatar
lesto committed
996 997 998 999

\item[Ability to trace the logic upwards.] Find a condition and see what
factors produced it.

lesto's avatar
lesto committed
1000 1001
\item[Clearer graphic representation.] Decision tables serve as a better
tool for understanding, both for the implementor and the analyst.
lesto's avatar
lesto committed
1002 1003
\end{description}

1004
Unlike decision trees, these decision tables group the \emph{results}
lesto's avatar
lesto committed
1005 1006 1007 1008 1009 1010 1011 1012 1013
together in a graphically meaningful way. Visualization of ideas helps in
understanding problems, particularly those problems that are too
complex to perceive in a linear way.

For instance, \Fig{fig2-5} clearly shows that the charge for
additional minutes does not depend on whether an operator assisted or not.
With this new understanding we can draw a simplified table, as shown
in \Fig{fig2-6}.

paysan's avatar
paysan committed
1014
\wepsfigt{fig2-6}{A simplified decision table.}
lesto's avatar
lesto committed
1015 1016 1017 1018 1019

%Page 057 in first edition

It's easy to get so enamored of one's analytic tools that one forgets
about the problem. The analyst must do more than carry out all
1020 1021 1022 1023
possibilities of a problem to the nth degree, as I have seen authors
of books on structured analysis recommend. That approach only
increases the amount of available detail. The problem solver must also
try to simplify the problem.
lesto's avatar
lesto committed
1024 1025 1026 1027

\begin{tip}
You don't understand a problem until you can simplify it.
\end{tip}
lesto's avatar
lesto committed
1028 1029 1030

\noindent If the goal of analysis is not only understanding, but
simplification, then perhaps we've got more work to do.
lesto's avatar
lesto committed
1031 1032

Our revised decision table (\Fig{fig2-6}) shows that the per-mile
1033 1034 1035 1036 1037 1038 1039
charge depends only on whether the rate is full, lower, or lowest. In
other words, it's subject to only one of the three dimensions shown in
the table.  What happens if we split this table into two tables, as in
\Fig{fig2-7}?

\wepsfiga{fig2-7}{The sectional decision table.}

lesto's avatar
lesto committed
1040 1041
Now we're getting the answer through a combination of table look-up
and calculation. The formula for the per-minute charge can be
1042
expressed as a pseudo\Forth{} definition:
lesto's avatar
lesto committed
1043 1044

\begin{Code}
1045 1046
: per-minute-charge ( -- per-minute-charge )
        connect-charge  mileage-charge  + ;
lesto's avatar
lesto committed
1047
\end{Code}
1048 1049
The ``\forth{+}'' now appears once in the definition,
not nine times in the table.
lesto's avatar
lesto committed
1050

1051
Taking the principle of calculation one step further, we note (or
lesto's avatar
lesto committed
1052
remember from the original problem statement) that operator assistance
1053 1054 1055
merely adds a one-time charge of .90 to the total charge. In this
sense, the operator charge is not a function of any of the three
dimensions. It's more
lesto's avatar
lesto committed
1056
%Page 058 in first edition
1057 1058
appropriately expressed as a ``logical calculation''; that is, a
function that combines logic with arithmetic:
lesto's avatar
lesto committed
1059 1060

\begin{Code}
1061 1062
: ?assistance  ( direct-dial-charge -- total-charge )
   operator? IF .90 + THEN ;
lesto's avatar
lesto committed
1063 1064
\end{Code}
(But remember, this charge applies only to the first minute.)
1065

paysan's avatar
paysan committed
1066
\wepsfigb{fig2-8}{The decision table without operator involvement depicted.}
1067

lesto's avatar
lesto committed
1068 1069 1070 1071
This leaves us with the simplified table shown in \Fig{fig2-8}, and an
increased reliance on expressing calculations. Now we're getting
somewhere.

paysan's avatar
paysan committed
1072
Let's go back to our definition of \forth{PER-MINUTE-CHARGE}:
lesto's avatar
lesto committed
1073
\begin{Code}
1074 1075
: per-minute-charge ( -- per-minute-charge )
   connect-charge  mileage-charge  + ;
lesto's avatar
lesto committed
1076 1077 1078 1079 1080 1081
\end{Code}
Let's get more specific about the rules for the connection charge and for
the mileage charge.

The connection charge depends on whether the minute is the first or
an additional minute. Since there are two kinds of per-minute charges,
1082
perhaps it will be easiest to rewrite \forth{PER-MINUTE-CHARGE} as two
lesto's avatar
lesto committed
1083 1084
different words.

1085 1086 1087 1088 1089
Let's assume we will build a component that will fetch the appropriate
rates from the table. The word \forth{1MINUTE} will get the rate for
the first minute; \forth{+MINUTES} will get the rate for each
additional minute.  Both of these words will depend on the time of day
to determine whether to use the full, lower, or lowest rates.
lesto's avatar
lesto committed
1090

1091
Now we can define the pair of words to replace \forth{PER-MINUTE-CHARGE}:
lesto's avatar
lesto committed
1092 1093 1094 1095

%Page 059 in first edition

\begin{Code}
1096 1097 1098 1099
: first  ( -- charge )
  1minute  ?assistance   mileage-charge + ;
: per-additional  ( -- charge )
   +minutes  mileage-charge + ;
lesto's avatar
lesto committed
1100
\end{Code}
1101 1102 1103 1104
What is the rule for the mileage charge? Very simple. It is the rate
(per hundred miles) times the number of miles (in hundreds). Let's
assume we can define the word \forth{MILEAGE-RATE}, which will fetch
the mileage rate from the table:
lesto's avatar
lesto committed
1105 1106

\begin{Code}
1107 1108
: mileage-charge  ( -- charge )
   #miles @  mileage-rate * ;
lesto's avatar
lesto committed
1109
\end{Code}
1110
Finally, if we know the total number of minutes for a call, we can now
lesto's avatar
lesto committed
1111 1112 1113
calculate the total direct-dial charge:

\begin{Code}
1114 1115 1116 1117 1118
: total   ( -- total-charge )
   first                        \ first minute rate
   ( #minutes) 1-               \ additional minutes
      per-additional *          \ times the rate
   +  ;                         \ added together
lesto's avatar
lesto committed
1119
\end{Code}
1120
We've expressed the rules to this particular problem through a
lesto's avatar
lesto committed
1121 1122
combination of simple tables and logical calculations.

1123
(Some final notes on this example: We've written something very close
1124
to a running \Forth{} application. But it is only pseudocode. We've
1125 1126
avoided stack manipulations by assuming that values will somehow be on
the stack where the comments indicate. Also, we've used hyphenated
lesto's avatar
lesto committed
1127
names because they might be more readable for the customer. Short
paysan's avatar
paysan committed
1128
names are preferred in real code---see \Chap{5}.)\program{phone2}
lesto's avatar
lesto committed
1129

1130 1131 1132 1133 1134
We'll unveil the finished code for this example in \Chap{8}.%
\index{A!Analysis!decision table|)}%
\index{A!Analysis!rule definition|)}%
\index{C!Conceptual model!rule definition|)}%
\index{D!Decision table|)}%
lesto's avatar
lesto committed
1135
\index{R!Rule definition|)}
lesto's avatar
lesto committed
1136

1137 1138 1139 1140 1141
\section{Defining the Data Structures}%
\index{A!Analysis!conceptual model|(}%
\index{A!Analysis!data structure definition|(}%
\index{C!Conceptual model|)}%
\index{C!Conceptual model!data structure definition|(}%
lesto's avatar
lesto committed
1142
\index{D!Data structures:!defining|(}
lesto's avatar
lesto committed
1143

1144 1145 1146 1147
After defining the interfaces, and sometimes defining the rules,
occasionally you'll need to define certain data structures as well.
We're not referring here to the implementation of the data structures,
but rather to a description of their conceptual model.
lesto's avatar
lesto committed
1148 1149

If you're automating a library index, for instance, a crucial portion
1150 1151 1152 1153 1154 1155
of your analysis will concern developing the logical data structure.
You'll have to decide what information will be kept for each book:
title, author, subject, etc. These ``attributes'' will comprise an
``entity'' (set of related records) called \forth{BOOKS}. Then you'll
have to determine what other data structures will be required to let
the users search the \forth{BOOKS} efficiently.
lesto's avatar
lesto committed
1156 1157 1158

%Page 060 in first edition

1159 1160
\wepsfigp{img2-060}{Given two adequate solutions,
the correct one is the simpler.}
lesto's avatar
lesto committed
1161 1162 1163

%Page 061 in first edition

paysan's avatar
paysan committed
1164 1165 1166 1167
%%! cut suggested by Leo
%You may need another entity consisting of authors' names in
%alphabetical order, along with ``attribute pointers'' to the books
%each author has written.
lesto's avatar
lesto committed
1168 1169

Certain constraints will also affect the conceptual model of the data
1170 1171 1172
structure. In the library index example, you need to know not only
\emph{what} information the users need, but also how long they're
willing to \emph{wait} to get it.
lesto's avatar
lesto committed
1173 1174

For instance, users can request listings of topics by year of
1175 1176 1177 1178
publication---say everything on ladies' lingerie between 1900 and
1910.  If they expect to get this information in the snap of a girdle,
you'll have to index on years and on topics. If they can wait a day,
you might just let the computer search through all the books in the
1179 1180 1181 1182
library.%
\index{A!Analysis!conceptual model|)}%
\index{A!Analysis!data structure definition|)}%
\index{C!Conceptual model!data structure definition|)}%
lesto's avatar
lesto committed
1183
\index{D!Data structures:!defining|)}
lesto's avatar
lesto committed
1184

1185 1186
\section{Achieving Simplicity}%
\index{A!Analysis!simplicity|(}%
lesto's avatar
lesto committed
1187
\index{S!Simplicity|(}
lesto's avatar
lesto committed
1188 1189 1190 1191 1192

\begin{tip}
Keep it simple.
\end{tip}

1193 1194
\noindent While you are taking these crucial first steps toward
understanding the problem, keep in mind the old saying:
lesto's avatar
lesto committed
1195

1196
\begin{tfquot}
1197
Given two solutions to a problem, the correct one is the simpler.
1198
\end{tfquot}
1199
This is especially true in software design. The simpler solution is often
lesto's avatar
lesto committed
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211
more difficult to discover, but once found, it is:

\begin{itemize}
\item easier to understand
\item easier to implement
\item easier to verify and debug
\item easier to maintain
\item more compact
\item more efficient
\item more fun
\end{itemize}

1212 1213
\begin{interview}
One of the most compelling advocates of simplicity is
paysan's avatar
paysan committed
1214
\person{Moore}\index{M!Moore, Charles|(}:
lesto's avatar
lesto committed
1215

1216
\begin{tfquot}
1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229
You need a feeling for the size of the problem. How much code should
it take to implement the thing? One block? Three? I think this is a
very useful design tool. You want to gut-feel whether it's a trivial
problem or a major problem, how much time and effort you should spend
on it.

When you're done, look back and say, ``Did I come up with a solution
that is reasonable?'' If your solution fills six screens, it may seem
you've used a sledgehammer to kill a mosquito. Your mental image is
out of proportion to the significance of the problem.

I've seen nuclear physics programs with hundreds of thousands of lines
of FORTRAN. Whatever that code does, it doesn't warrant hundreds of
lesto's avatar
lesto committed
1230
%Page 062 in first edition
1231 1232 1233 1234
thousands of lines of code. Probably its writers have overgeneralized
the problem. They've solved a large problem of which their real needs
are a subset. They have violated the principle that the solution
should match the problem.
lesto's avatar
lesto committed
1235
\end{tfquot}\index{M!Moore, Charles|)}
1236
\end{interview}
lesto's avatar
lesto committed
1237 1238 1239 1240
\begin{tip}
Generality usually involves complexity. Don't generalize your solution any
more than will be required; instead, keep it changeable.
\end{tip}
1241
\begin{interview}
paysan's avatar
paysan committed
1242
\person{Moore} continues:\index{M!Moore, Charles|(}
1243
\begin{tfquot}
lesto's avatar
lesto committed
1244

1245
Given a problem, you can code a solution to it. Having done that, and found
lesto's avatar
lesto committed
1246 1247 1248
certain unpleasantnesses to it, you can go back and change the problem,
and end up with a simpler solution.

1249
There's a class of device optimization---minimizing the number of gates in a
lesto's avatar
lesto committed
1250 1251 1252 1253 1254 1255 1256 1257 1258 1259
circuit-where you take advantage of the ``don't care'' situation. These
occur either because a case won't arise in practice or because you really
don't care. But the spec is often written by people who have no appreciation
for programming. The designer may have carefully specified all the cases,
but hasn't told you, the programmer, which cases are really important.

If you are free to go back and argue with him and take advantage of the
``don't cares,'' you can come up with a simpler solution.

Take an engineering application, such as a 75-ton metal powder press,
lesto's avatar
lesto committed
1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282
stamping out things. They want to install a computer to control the
valves in place of the hydraulic control previously used. What kind of
spec will you get from the engineer? Most likely the sensors were
placed for convenience from an electromechanical standpoint. Now they
could be put somewhere else, but the engineer has forgotten. If you
demand explanations, you can come closer to the real world and further
from their model of the world.

Another example is the PID (proportional integration and
differentiation) algorithm for servos. You have one term that
integrates, another term that differentiates, and a third term that
smooths. You combine those with 30\% integration, 10\%
differentiation, or whatever. But it's only a digital filter. It used
to be convenient in analog days to break out certain terms of the
digital filter and say, ``This is the integrator and this is the
differentiator. I'll make this with a capacitor and I'll make that
with an inductor.''

Again the spec writers will model the analog solution which was
modeling the electromechanical solution, and they're several models
away from reality. In fact, you can replace it all with two or three
coefficients in a digital filter for a much cleaner, simpler and more
efficient solution.
lesto's avatar
lesto committed
1283
\end{tfquot}\index{M!Moore, Charles|)}
1284
\end{interview}
lesto's avatar
lesto committed
1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296

\begin{tip}
Go back to what the problem was before the customer tried to solve it.
Exploit the ``don't cares.''
\end{tip}

%Page 063 in first edition

\wepsfigp{img2-063}{An overgeneralized solution.}

%Page 064 in first edition

1297
\begin{interview}
paysan's avatar
paysan committed
1298
\person{Moore} continues:\index{M!Moore, Charles|(}
lesto's avatar
lesto committed
1299

1300
\begin{tfquot}
lesto's avatar
lesto committed
1301
Sometimes the possibilities for simplification aren't immediately
lesto's avatar
lesto committed
1302 1303
obvious.

1304 1305 1306
There's this problem of zooming in a digitized graphics display, such
as CAD systems. You have a picture on the screen and you want to zoom
in on a portion to see the details.
lesto's avatar
lesto committed
1307 1308

I used to implement it so that you move the cursor to the position of
1309 1310 1311 1312
interest, then press a button, and it zooms until you have a window of
the desired size. That was the way I've always done it. Until I
realized that that was stupid. I never needed to zoom with such fine
resolution.
lesto's avatar
lesto committed
1313

1314 1315 1316 1317 1318
So instead of moving the cursor a pixel at a time, I jump the cursor
by units of, say, ten. And instead of increasing the size of box, I
jump the size of the box. You don't have a choice of sizes. You zoom
by a factor of four. The in-between sizes are not interesting. You can
do it as many times as you like.
lesto's avatar
lesto committed
1319

paysan's avatar
paysan committed
1320
By quantizing things fairly brutally, you make it easier to work with,
lesto's avatar
lesto committed
1321
more responsive, and simpler.
lesto's avatar
lesto committed
1322
\end{tfquot}\index{M!Moore, Charles|)}
1323
\end{interview}
lesto's avatar
lesto committed
1324 1325

\begin{tip}
paysan's avatar
paysan committed
1326
To simplify, quantize.\index{Q!Quantization}
lesto's avatar
lesto committed
1327 1328
\end{tip}

1329
\begin{interview}
paysan's avatar
paysan committed
1330
\person{Moore} concludes:\index{M!Moore, Charles|(}%
1331
\begin{tfquot}
1332 1333 1334 1335
It takes arrogance to go back and say ``You didn't really mean this,''
or ``Would you mind if I took off this page and replaced it with this
expression?'' They get annoyed. They want you to do what they told you
to do.
lesto's avatar
lesto committed
1336

lesto's avatar
lesto committed
1337
\index{S!Stuart, LaFarr|(}
paysan's avatar
paysan committed
1338
\person{LaFarr Stuart} took this attitude when he redesigned \Forth{}
lesto's avatar
lesto committed
1339
\cite{stuart80}. He didn't like the input buffer, so he implemented
1340
\Forth{} without it, and discovered he didn't really need an input buffer.%
lesto's avatar
lesto committed
1341
\index{S!Stuart, LaFarr|)}
lesto's avatar
lesto committed
1342

1343 1344
If you can improve the problem, it's a great situation to get into.
It's much more fun redesigning the world than implementing it.
lesto's avatar
lesto committed
1345
\end{tfquot}\index{M!Moore, Charles|)}
1346
\end{interview}
lesto's avatar
lesto committed
1347

1348 1349 1350
\noindent Effective programmers learn to be tactful and to couch their
approaches in non-threatening ways: ``What would be the consequences
of replacing that with this?'' etc.
lesto's avatar
lesto committed
1351 1352 1353 1354 1355 1356

Yet another way to simplify a problem is this:

\begin{tip}
To simplify, keep the user out of trouble.
\end{tip}
lesto's avatar
lesto committed
1357 1358 1359
\noindent Suppose you're designing part of a word processor that
displays a directory of stored documents on the screen, one per line.
You plan that the
lesto's avatar
lesto committed
1360 1361
%Page 065 in first edition
user can move the cursor next to the name of any document, then type a
1362 1363
one-letter command indicating the chosen action: ``p'' for print,
``e'' for edit, etc.
lesto's avatar
lesto committed
1364 1365 1366

Initially it seems all right to let the user move the cursor anywhere
on the screen. This means that those places where text already appears
1367
must be protected from being overwritten. This implies a concept of
paysan's avatar
paysan committed
1368
``protected fields'' and special handling. A simpler approach confines
1369 1370
the cursor to certain fields, possibly using reverse video to let the
user see the size of the allowable field.
lesto's avatar