TweetFollow Us on Twitter

Manual First
Volume Number:1
Issue Number:8
Column Tag:Software Souffle

"Do the Manual First!"

By John Bogan, Microcomputing Consultant, MacTutor Contributing Editor

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 subsystems, 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 especially 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


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.


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.

Getting Started

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.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Civilization VI 1.1.0 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
Network Radar 2.3.3 - $17.99
Network Radar is an advanced network scanning and managing tool. Featuring an easy-to-use and streamlined design, the all-new Network Radar 2 has been engineered from the ground up as a modern Mac... Read more
Printopia 3.0.8 - Share Mac printers wit...
Run Printopia on your Mac to share its printers to any capable iPhone, iPad, or iPod Touch. Printopia will also add virtual printers, allowing you to save print-outs to your Mac and send to apps.... Read more
ForkLift 3.2.1 - Powerful file manager:...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
BetterTouchTool 2.417 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Little Snitch 4.0.6 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Google Chrome 65.0.3325.181 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
TeamViewer 13.1.2991 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for non... Read more
Printopia 3.0.8 - Share Mac printers wit...
Run Printopia on your Mac to share its printers to any capable iPhone, iPad, or iPod Touch. Printopia will also add virtual printers, allowing you to save print-outs to your Mac and send to apps.... Read more
BetterTouchTool 2.417 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more

Latest Forum Discussions

See All

The best games that came out for iPhone...
It's not a huge surprise that there's not a massive influx of new, must-buy games on the App Store this week. After all, GDC is happening, so everyone's busy at parties and networking and dying from a sinister form of jetlag. That said, there are... | Read more »
Destiny meets its mobile match - Everyth...
Shadowgun Legends is the latest game in the Shadowgun series, and it's taking the franchise in some interesting new directions. Which is good news. The even better news is that it's coming out tomorrow, so if you didn't make it into the beta you... | Read more »
How PUBG, Fortnite, and the battle royal...
The history of the battle royale genre isn't a long one. While the nascent parts of the experience have existed ever since players first started killing one another online, it's really only in the past six years that the genre has coalesced into... | Read more »
Around the Empire: What have you missed...
Oh hi nice reader, and thanks for popping in to check out our weekly round-up of all the stuff that you might have missed across the Steel Media network. Yeah, that's right, it's a big ol' network. Obviously 148Apps is the best, but there are some... | Read more »
All the best games on sale for iPhone an...
It might not have been the greatest week for new releases on the App Store, but don't let that get you down, because there are some truly incredible games on sale for iPhone and iPad right now. Seriously, you could buy anything on this list and I... | Read more »
Everything You Need to Know About The Fo...
In just over a week, Epic Games has made a flurry of announcements. First, they revealed that Fortnite—their ultra-popular PUBG competitor—is coming to mobile. This was followed by brief sign-up period for interested beta testers before sending out... | Read more »
The best games that came out for iPhone...
It's not been the best week for games on the App Store. There are a few decent ones here and there, but nothing that's really going to make you throw down what you're doing and run to the nearest WiFi hotspot in order to download it. That's not to... | Read more »
Death Coming (Games)
Death Coming Device: iOS Universal Category: Games Price: $1.99, Version: (iTunes) Description: --- Background Story ---You Died. Pure and simple, but death was not the end. You have become an agent of Death: a... | Read more »
Hints, tips, and tricks for Empires and...
Empires and Puzzles is a slick match-stuff RPG that mixes in a bunch of city-building aspects to keep things fresh. And it's currently the Game of the Day over on the App Store. So, if you're picking it up for the first time today, we thought it'd... | Read more »
What You Need to Know About Sam Barlow’s...
Sam Barlow’s follow up to Her Story is #WarGames, an interactive video series that reimagines the 1983 film WarGames in a more present day context. It’s not exactly a game, but it’s definitely still interesting. Here are the top things you should... | Read more »

Price Scanner via

Thursday roundup of the best 13″ MacBook Pro...
B&H Photo has new 2017 13″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only. Their prices are the lowest available for... Read more
Sale: 9.7-inch 2017 WiFi iPads starting at $2...
B&H Photo has 9.7″ 2017 WiFi Apple iPads on sale for $40 off MSRP for a limited time. Shipping is free, and pay sales tax in NY & NJ only: – 32GB iPad WiFi: $289, $40 off – 128GB iPad WiFi: $... Read more
Roundup of Certified Refurbished iPads, iPad...
Apple has Certified Refurbished 9.7″ WiFi iPads available for $50-$80 off the cost of new models. An Apple one-year warranty is included with each iPad, and shipping is free: – 9″ 32GB WiFi iPad: $... Read more
Back in stock! Apple’s full line of Certified...
Save $300-$300 on the purchase of a 2017 13″ MacBook Pro today with Certified Refurbished models at Apple. Apple’s refurbished prices are the lowest available for each model from any reseller. A... Read more
Wednesday deals: Huge sale on Apple 15″ MacBo...
Adorama has new 2017 15″ MacBook Pros on sale for $250-$300 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 15″ 2.8GHz Touch Bar MacBook Pro Space Gray (MPTR2LL/A): $... Read more
Apple offers Certified Refurbished Series 3 A...
Apple has Certified Refurbished Series 3 Apple Watch GPS models available for $50, or 13%, off the cost of new models. Apple’s standard 1-year warranty is included, and shipping is free. Numerous... Read more
12″ 1.2GHz Space Gray MacBook on sale for $11...
B&H Photo has the Space Gray 12″ 1.2GHz MacBook on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 12″ 1.2GHz Space Gray MacBook: $1199 $... Read more
Mac minis available for up to $150 off MSRP w...
Apple has restocked Certified Refurbished Mac minis starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Back in stock: 13-inch 2.5GHz MacBook Pro (Ce...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros (MD101LL/A) available for $829, or $270 off original MSRP. Apple’s one-year warranty is standard, and shipping is free: – 13″ 2.5GHz MacBook... Read more
Apple restocks Certified Refurbished 2017 13″...
Apple has Certified Refurbished 2017 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: – 13″ 1.8GHz/8GB/128GB MacBook Air (... Read more

Jobs Board

*Apple* Genius - Technical Customer Service...
Job Description:Job SummaryAs a Genius at the Apple Store, you maintain customers' trust in Apple as the skilled technical customer service expert, Read more
Metadata Operations Specialist, *Apple* Med...
# Metadata Operations Specialist, Apple Media Products Job Number: 113387726 Santa Clara Valley, California, United States Posted: 08-Feb-2018 Weekly Hours: 40.00 Read more
*Apple* Retail - Multiple Positions - Apple,...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Data Scientist, *Apple* Ecosystem (AMP Anal...
# Data Scientist, Apple Ecosystem (AMP Analytics) Job Number: 113428728 Santa Clara Valley, California, United States Posted: 24-Jan-2018 Weekly Hours: 40.00 **Job Read more
*Apple* Professional Learning Specialist - A...
# Apple Professional Learning Specialist Job Number: 113456892 Englewood, NJ, New Jersey, United States Posted: 02-Feb-2018 Weekly Hours: 40.00 **Job Summary** The Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.