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

Problem:

1) MacTutor needs a good example of Modula-2 code for the Apple Macintosh featuring elements of the Mac 'face and the toolbox calls.

2) The world is a bit boring and we could use a nice little game to liven up the day.

Solution:

The Towers of Hanoi a 1,000 year old puzzle with an automatic solution option.

Introduction

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

Microsoft Remote Desktop 8.0.16 - Connec...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
Spotify 1.0.4.90. - Stream music, create...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
djay Pro 1.1 - Transform your Mac into a...
djay Pro provides a complete toolkit for performing DJs. Its unique modern interface is built around a sophisticated integration with iTunes and Spotify, giving you instant access to millions of... Read more
Vivaldi 1.0.118.19 - Lightweight browser...
Vivaldi browser. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind that users are... Read more
Stacks 2.6.11 - New way to create pages...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features: Fluid Layout: Stacks lets you build pages... Read more
xScope 4.1.3 - Onscreen graphic measurem...
xScope is powerful set of tools that are ideal for measuring, inspecting, and testing on-screen graphics and layouts. Its tools float above your desktop windows and can be accessed via a toolbar,... Read more
Cyberduck 4.7 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Labels & Addresses 1.7 - Powerful la...
Labels & Addresses is a home and office tool for printing all sorts of labels, envelopes, inventory labels, and price tags. Merge-printing capability makes the program a great tool for holiday... Read more
teleport 1.2.1 - Use one mouse/keyboard...
teleport is a simple utility to let you use one single mouse and keyboard to control several of your Macs. Simply reach the edge of your screen, and your mouse teleports to your other Mac! The... Read more
Apple iMovie 10.0.8 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more

Use Batting Average and the Apple Watch...
Batting Average, by Pixolini, is designed to help you manage your statistics. Every time you go to bat, you can use your Apple Watch to track  your swings, strikes, and hits. [Read more] | Read more »
Celebrate Studio Pango's 3rd Annive...
It is time to party, Pangoland pals! Studio Pango is celebrating their 3rd birthday and their gift to you is a new update to Pangoland. [Read more] | Read more »
Become the World's Most Important D...
Must Deliver, by cherrypick games, is a top-down endless-runner witha healthy dose of the living dead. [Read more] | Read more »
SoundHound + LiveLyrics is Making its De...
SoundHound Inc. has announced that SoundHound + LiveLyrics, will be one of the first third-party apps to hit the Apple Watch. With  SoundHound you'll be able to tap on your watch and have the app recognize the music you are listening to, then have... | Read more »
Adobe Joins the Apple Watch Lineup With...
A whole tidal wave of apps are headed for the Apple Watch, and Adobe has joined in with 3 new ways to enhance your creativity and collaborate with others. The watch apps pair with iPad/iPhone apps to give you total control over your Adobe projects... | Read more »
Z Steel Soldiers, Sequel to Kavcom'...
Kavcom has released Z Steel Soldiers, which continues the story of the comedic RTS originally created by the Bitmap Brothers. [Read more] | Read more »
Seene Lets You Create 3D Images With You...
Seene, by Obvious Engineering, is a 3D capture app that's meant to allow you to create visually stunning 3D images with a tap of your finger, and then share them as a 3D photo, video or gif. [Read more] | Read more »
Lost Within - Tips, Tricks, and Strategi...
Have you just downloaded Lost Within and are you in need of a guiding hand? While it’s not the toughest of games out there you might still want some helpful tips to get you started. [Read more] | Read more »
Entertain Your Pet With Your Watch With...
The Petcube Camera is a device that lets you use live video to check in on your pet, talk to them, and play with them using a laser pointer - all while you're away. And the Petcube app is coming to the Apple Watch, so you'll be able to hang out with... | Read more »
Now You Can Manage Your Line2 Calls With...
You'll be able to get your Line2 cloud phone service on the Apple Watch very soon. The watch app can send and receive messages using hands-free voice dictation, or by selecting from a list of provided responses. [Read more] | Read more »

Price Scanner via MacPrices.net

Intel Compute Stick: A New Mini-Computing For...
The Intel Compute Stick, a new pocket-sized computer based on a quad-core Intel Atom processor running Windows 8.1 with Bing, is available now through Intel Authorized Dealers across much of the... Read more
Heal to Launch First One-Touch House Call Doc...
Santa Monica, California based Heal, a pioneer in on-demand personal health care services — will offer the first one-touch, on-demand house call doctor app for the Apple Watch. Heal’s Watch app,... Read more
Mac Notebooks: Avoiding MagSafe Power Adapter...
Apple Support says proper usage, care, and maintenance of Your Mac notebook’s MagSafe power adapter can substantially increase the the adapter’s service life. Of course, MagSafe itself is an Apple... Read more
12″ Retina MacBook In Shootout With Air And P...
BareFeats’ rob-ART morgan has posted another comparison of the 12″ MacBook with other Mac laptops, noting that the general goodness of all Mac laptops can make which one to purchase a tough decision... Read more
FileMaker Go for iPad and iPhone: Over 1.5 Mi...
FileMaker has announced that its FileMaker Go for iPad and iPhone app has surpassed 1.5 million downloads from the iTunes App Store. The milestone confirms the continued popularity of the FileMaker... Read more
Sale! 13-inch 2.7GHz Retina MacBook Pro for $...
 Best Buy has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale for $1099 – $200 off MSRP. Choose free shipping or free local store pickup (if available). Price for online orders only, in-... Read more
Minimalist MacBook Confirms Death of Steve Jo...
ReadWrite’s Adriana Lee has posted a eulogy for the “Digital Hub” concept Steve Jobs first proposed back in 2001, declaring the new 12-inch MacBook with its single, over-subscribed USB-C port to be... Read more
13-inch 2.7GHz Retina MacBook Pro for $1234 w...
Adorama has the 13″ 2.7GHz/128GB Retina MacBook Pro in stock for $1234.99 ($65 off MSRP) including free shipping plus a free LG external DVD/CD optical drive. Adorama charges sales tax in NY & NJ... Read more
13-inch 2.5GHz MacBook Pro available for $999...
 Adorama has the 13-inch 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
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
*Apple* Support Technician IV - Jack Henry a...
Job Description Jack Henry & Associates is seeking an Apple Support Technician. This position while acting independently, ensures the proper day-to-day control of Read more
*Apple* Client Systems Solution Specialist -...
…drive revenue and profit in assigned sales segment and/or region specific to the Apple brand and product sets. This person will work directly with CDW Account Managers Read more
*Apple* Software Support - Casper (Can work...
…experience . Full knowledge of Mac OS X and prior . Mac OSX / Server . Apple Remote Desktop . Process Documentation . Ability to prioritize multiple tasks in a fast pace Read more
*Apple* Software Support - Xerox Corporation...
…Imaging experience Full knowledge of Mac OS X and prior Mac OSX / Server Apple Remote Desktop Process Documentation Ability to prioritize multiple tasks in a fast pace Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.