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

Xcode 15.0.1 - Integrated development en...
Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing... Read more
Google Chrome 120.0.6099.62 - 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
Dropbox 188.4.6302 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
djay Pro 5.0 - 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
Things 3.19.4 - Elegant personal task ma...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
Sublime Text 4169 - Sophisticated text e...
Sublime Text is a sophisticated text editor for code, markup, and prose. You'll love the slick user interface, extraordinary features, and amazing performance. Features Goto Anything. Use Goto... Read more
Typinator 9.1 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
ESET Cyber Security 6.11.414.0 - Basic i...
ESET Cyber Security provides powerful protection against phishing, viruses, worms, and spyware. Offering similar functionality to ESET NOD32 Antivirus for Windows, ESET Cyber Security for Mac allows... Read more
Opera 105.0.4970.29 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
Quicken 7.4.1 - Complete personal financ...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more

Latest Forum Discussions

See All

Vampire Survivors Among Us Crossover Eme...
Day of the Devs The Game Awards 2023 Edition just aired, and there were a plethora of announcements of great indie games and updates. I’ll have a round-up of the ones I liked the most in the SwitchArcade, but poncle just announced the first... | Read more »
‘Refind Self: The Personality Test Game’...
The last two months have been so busy that I’ve not been able to make time to play many games until recently. There are still new games coming out even as we head closer to the holidays, but I finally managed to play Playism and Lizardry’s recent... | Read more »
Experience the glory of the Northern Lig...
Dinosaur Polo Club, one of the best developer names out there, have recently announced the final update of 2023 for Mini Motorways. Instead of embracing Christmas, this event is instead inspired by one of the most beautiful natural phenomena, the... | Read more »
‘Disney Dreamlight Valley Arcade Edition...
After a bit of a delay, Disney Dreamlight Valley Arcade Edition () is now available on Apple Arcade worldwide. When Disney Dreamlight Valley Arcade Edition hit early access on PC and consoles including Nintendo Switch, I always assumed it would... | Read more »
‘Devil May Cry: Peak of Combat’ Releases...
It feels like we’ve been covering Devil May Cry: Peak of Combat (), the mobile entry in the superb Devil May Cry series, for as long as we were waiting for Devil May Cry 5. After trailers revealing gameplay, characters, controller support, betas,... | Read more »
‘Marvel Snap’ Dons Its Finest in the New...
It’s been quite a year for the card battler Marvel Snap (Free), which is still one of my favorite mobile games. There have been a bunch of interestingly-themed seasons, sometimes connected to the MCU and sometimes just doing their own thing. Plenty... | Read more »
SwitchArcade Round-Up: ‘A Highland Song’...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for December 5th, 2023. It’s a bit of a short one today since I was busy with a variety of other things, but there are several new releases for us to summarize. There are some really... | Read more »
‘Metal Slug ACA NEOGEO’ Review – Another...
Well, here we go again. The latest addition to SNK and Hamster’s mobile Arcade Archives line is none other than Metal Slug ACA NEOGEO ($3.99), a second take on a game we got a mobile version of a decade back from Dotemu. That was a fine version for... | Read more »
‘Sonic Dream Team’ Apple Arcade Review –...
What an unusual day we have arrived upon today. Now, Sonic the Hedgehog games aren’t a new thing for iOS gaming. The original Sonic the Hedgehog appeared on the classic iPod, so the Blue Blur got in the doors as fast as you would expect him to. The... | Read more »
PvP Basketball Game ‘NBA Infinite’ Annou...
Level Infinite and Lightspeed Studios just announced a new real-time PvP basketball game for mobile in the form of NBA Infinite (). NBA Infinite includes solo modes as well, collecting and upgrading current NBA players, managing teams, and more. It... | Read more »

Price Scanner via MacPrices.net

Apple’s 14-inch M3 MacBook Pros are on Holida...
Best Buy is offering a $150-$200 discount on Space Gray or Silver 14″ M3 MacBook Pros on their online store with prices available starting at $1449 ($1399 for premium My Best Buy members). Prices... Read more
Holiday Sale: 128GB iPhone 15 Pro, 15 Plus, o...
Boost Infinite, part of MVNO Boost Mobile using AT&T and T-Mobile’s networks, is offering the 128GB iPhone 15 Pro, 128GB iPhone 15 Plus, or 128GB & 256GB iPhone 15 for $60 per month including... Read more
Clearance 12.9-inch iPad Pros with M1 CPUs av...
Apple has Certified Refurbished, previous-generation, 12″ M1 iPad Pros available in their online store in a variety of configurations. Models start at $889 and range up to $350 off Apple’s original... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Holiday sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
B&H is offering a $150 discount on 13-inc...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock today and on Holiday sale for $150 off Apple’s MSRP, only $949. Free 1-2 day delivery is available to most US addresses.... Read more
Apple is clearing out last year’s M1-powered...
Apple has Certified Refurbished 11″ M1 iPad Pros available starting at $639 and ranging up to $310 off Apple’s original MSRP. Each iPad Pro comes with Apple’s standard one-year warranty, features a... Read more
Save $50 on these HomePods available today at...
Apple has Certified Refurbished White and Midnight HomePods available for $249, Certified Refurbished. That’s $50 off MSRP and the lowest price currently available for a full-size Apple HomePod this... Read more
New 16-inch M3 Pro MacBook Pros are on sale f...
Holiday MacBook deals are live at B&H Photo. Apple 16″ MacBook Pros with M3 Pro CPUs are in stock and on sale for $200-$250 off MSRP. Their prices are among the lowest currently available for... Read more
Christmas Deal Alert! Apple AirPods Pro with...
Walmart has Apple’s 2023 AirPods Pro with USB-C in stock and on sale for $189.99 on their online store as part of their Holiday sale. Their price is $60 off MSRP, and it’s currently the lowest price... Read more
Apple has Certified Refurbished iPhone 12 Pro...
Apple has unlocked Certified Refurbished iPhone 12 Pro models in stock starting at $589 and ranging up to $350 off original MSRP. Apple includes a standard one-year warranty and new outer shell with... Read more

Jobs Board

Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Mobile Platform Engineer ( *Apple* /AirWatch)...
…systems, installing and maintaining certificates, navigating multiple network segments and Apple /IOS devices, Mobile Device Management systems such as AirWatch, and Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.