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

Corel Painter 20.1.0.285 - Digital art s...
Corel Painter lets you advance your digital art style with painted textures, subtle glazing brushwork, interactive gradients, and realistic Natural-Media. Easily transition from traditional to... Read more
iTubeDownloader 6.5.19 - Easily download...
iTubeDownloader is a powerful-yet-simple YouTube downloader for the masses. Because it contains a proprietary browser, you can browse YouTube like you normally would. When you see something you want... Read more
OmniFocus 3.8 - GTD task manager with iO...
OmniFocus is an organizer app. It uses projects to organize tasks naturally, and then add tags to organize across projects. Easily enter tasks when you’re on the go, and process them when you have... Read more
Hazel 4.4.5 - Create rules for organizin...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a familiar... Read more
Macs Fan Control 1.5.7 - Monitor and con...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
Acorn 6.6 - Bitmap image editor.
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
OnyX 3.8.2 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
macOS Catalina 10.15.5 - An Operating Sy...
macOS Catalina gives you more of everything you love about Mac. Experience three all-new media apps: Apple Music, Apple TV, and Apple Podcasts. Locate a missing Mac with the new Find My app. And now... Read more
macOS High Sierra Security Updates 10.13...
macOS High Sierra introduces new core technologies that improve the most important functions of your Mac. From rearchitecting how it stores your data to improving the efficiency of video streaming to... Read more
Numi 3.28 - Menu-bar calculator supports...
Numi is a calculator that magically combines calculations with text, and allows you to freely share your computations. Numi combines text editor and calculator Support plain English. For example, '5... Read more

Latest Forum Discussions

See All

Steam Link Spotlight - Signs of the Sojo...
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was XCOM: Chimera Squad. Read about how it plays using Steam Link's new mouse and keyboard support over here. | Read more »
Steampunk Tower 2, DreamGate's sequ...
Steampunk Tower 2 is a DreamGate's follow up to their previous tower defence game. It's available now for both iOS and Android as a free-to-play title and will see players defending their lone base by kitting it out with a variety of turrets. [... | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Pokemon Go Fest 2020 will be a virtual e...
Niantic has announced that Pokemon Go Fest will still take place this year although understandably it won't be a physical event. Instead, it will become a virtual celebration and is set to be held on 25th and 26th July. [Read more] | Read more »
Marvel Future Fight's major May upd...
Marvel Future Fight's latest update has now landed, and it sounds like a big one. The focus this time around is on Marvel's Guardians of the Galaxy, and it introduces all-new characters, quests, and uniforms for players to collect. [Read more] | Read more »
SINoALICE, Yoko Taro and Pokelabo's...
Yoko Taro and developer Pokelabo's SINoALICE has now opened for pre-registration over on the App Store. It's already amassed 1.5 million Android pre-registrations, and it's currently slated to launch on July 1st. [Read more] | Read more »
Masketeers: Idle Has Fallen's lates...
Masketeers: Idle Has Fallen is the latest endeavour from Appxplore, the folks behind Crab War, Thor: War of Tapnarok and Light A Way. It's an idle RPG that's currently available for Android in Early Access and will head to iOS at a later date. [... | Read more »
Evil Hunter Tycoon celebrates 2 million...
Evil Hunter Tycoon has proved to be quite the hit since launching back in March, with its most recent milestone being 2 million downloads. To celebrate the achievement, developer Super Planet has released a new updated called Darkness' Front Yard... | Read more »
Peak's Edge is an intriguing roguel...
Peak's Edge is an upcoming roguelike puzzle game from developer Kenny Sun that's heading for both iOS and Android on June 4th as a free-to-play title. It will see players rolling a pyramid shape through a variety of different levels. [Read more] | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »

Price Scanner via MacPrices.net

New 16″ MacBook Pros now on sale for up to $2...
Apple reseller DataVision is now offering new 16″ Apple MacBook Pros for up to $255 off MSRP, each including free shipping. Prices start at $2194. DataVision charges sales tax for NY, NJ, PA, and CA... Read more
Apple now offering Certified Refurbished iPho...
Apple is now offering Certified Refurbished iPhone Xr models in the refurbished section of their online store starting at $499. Each iPhone comes with Apple’s standard one-year warranty, ships free,... Read more
Sale! Get a 10.2″ 32GB WiFi iPad for only $27...
Walmart has new 10.2″ 32GB WiFi iPads on sale for $50 off Apple’s MSRP, only $279. These are the same iPads sold by Apple in their retail and online stores. Be sure to select Walmart as the seller... Read more
Apple resellers offer new 2020 Mac minis for...
Apple resellers are offering new 2020 Mac minis for up to $50 off Apple’s MSRP with prices available starting at $759. Shipping is free: (1) B&H Photo: – 2020 4-Core Mac mini: $759 $40 off MSRP... Read more
Sprint is offering the Apple iPhone 11 free t...
Did you miss out on Sprint’s recent free iPhone SE promotion? No worries. Sprint has the 64GB iPhone 11 available for $0 per month for new lines when you trade-in a qualifying phone in any condition... Read more
Apple has clearance 2019 13″ 1.4GHz MacBook P...
Apple has Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available today starting at $979 and up to $440 off original MSRP. Apple’s one-year warranty is included, shipping is... Read more
Apple restocks 2019 MacBook Airs starting at...
Apple has clearance, Certified Refurbished, 2019 13″ MacBook Airs available again starting at $779. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is... Read more
Apple restocks clearance Mac minis for only $...
Apple has restocked Certified Refurbished 2018 4-Core Mac minis for only $599. Each mini comes with a new outer case plus a standard Apple one-year warranty. Shipping is free: – 3.6GHz Quad-Core... Read more
Apple’s new 2020 13″ MacBook Airs on sale for...
B&H Photo has Apple’s new 2020 13″ 4-Core and 6-Core MacBook Airs on sale today for $50-$100 off Apple’s MSRP, starting at $949. Expedited shipping is free to many addresses in the US. The... Read more
B&H continues to offer clearance 2019 13″...
B&H Photo has clearance 2019 13″ 4-Core MacBook Pros available for up to $300 off Apple’s original MSRP, with prices starting at $1149. Expedited shipping is free to many addresses in the US. B... Read more

Jobs Board

Security Officer - *Apple* Store - NANA (Un...
**Security Officer \- Apple Store** **Description** About NMS Built on a culture of safety and integrity, NMSdelivers award\-winning, integrated support services to Read more
Transition Into Practice Program (TIP) - Sept...
…Academy-Transition into Practice (TIP) Residency program at St Mary Medical Center in Apple Valley, CA. **We are seekingRegistered Nurses who are:** + New graduate Read more
Essbase Developer - *Apple* - Theorem, LLC...
Job Summary Apple is seeking an experienced, detail-minded Essbase developer to join our worldwide business development and strategy team. If you are someone who Read more
Senior Software Engineer @ *Apple* - Theore...
Job Summary Apple is looking for a seasoned senior software engineer to join our worldwide business development and strategy team. This is an opportunity to lead a Read more
Cub Foods - *Apple* Valley - Now Hiring Par...
Cub Foods - Apple Valley - Now Hiring Part Time! United States of America, Minnesota, Apple Valley Retail Operations Post Date May 18, 2020 Requisition # 119230 Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.