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

Notion 2.1.9 - A unified workspace for m...
Notion is the unified workspace for modern teams. Features: Integration with Slack Documents Wikis Tasks More guests: invite up to 10 collaborators, friends & family to your pages Page... Read more
Spotify 1.2.0.1165 - Stream music, creat...
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
Thunderbird 102.5.1 - Email client from...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Pinegrow 7.03 - Mockup and design web pa...
Pinegrow (was Pinegrow Web Designer) is desktop app that lets you mockup and design webpages faster with multi-page editing, CSS and LESS styling, and smart components for Bootstrap, Foundation,... Read more
Adobe After Effects 2022 23.1 - Create p...
The new, more connected Adobe After Effects can make the impossible possible. Get powerful new features like a Live 3D Pipeline that brings CINEMA 4D scenes in as layers - without intermediate... Read more
SteerMouse 5.6.7 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. SteerMouse can assign various functions to buttons that Apple's software does not allow, including double-clicks, modifier clicks,... Read more
Wireshark 4.0.2 - Network protocol analy...
Wireshark is one of the world's foremost network protocol analyzers, and is the standard in many parts of the industry. It is the continuation of a project that started in 1998. Hundreds of... Read more
Adobe Premiere Pro 2022 23.1 - Digital v...
Adobe Premiere Pro is available as part of Adobe Creative Cloud for as little as $54.99/month. The price on display is a price for annual by-monthly plan for Adobe Premiere Pro only. Adobe Premiere... Read more
1Password 8.9.10 - Powerful password man...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
FotoMagico 6.3 - Powerful slideshow crea...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more

Latest Forum Discussions

See All

SwitchArcade Round-Up: ‘Chained Echoes’,...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for December 8th, 2022. Today is Thursday, and that usually means an absolute deluge of new releases on the eShop. But the year is winding down, so we’ve only got ten or so to look at... | Read more »
‘Awaken Legends: Idle RPG’ Celebrates th...
Awaken Legends: Idle RPG is adding its first update since the game was soft-launched in November, letting players get their hands on a new hero “Hera Valen". Players can also look forward to the Covenant of the Dark Knight event and the Wishing Well... | Read more »
‘Horizon Chase 2’ Japan World Tour Expan...
Horizon Chase 2 () from Aquiris is getting a major expansion today on Apple Arcade. The Japan World Tour expansion brings in 11 new races across 9 cities and it should be rolling out now as of this writing. I expect it to be available worldwide... | Read more »
Dark Fantasy Visual Novel ‘The 13th Mont...
Originally announced for release in August, The 13th Month from Japanese developer Kobayashimaru and publisher Kodansha released on PC via Steam worldwide this month. The dark fantasy visual novel that reimagines the classic Sleeping Beauty tale, is... | Read more »
Tom Clancey’s The Divison Resurgence ann...
Ubisoft has announced the latest Live Test dates for Tom Clancy’s The Division Resurgence, the hotly anticipated mobile entry in the Divison series. Starting December 8th and ending on the 22nd, the test will offer a huge amount of content for the... | Read more »
‘Easy Come Easy Golf’ New Update Adds St...
Easy Come Easy Golf () from Clap Hanz is one of my favorite games on Apple Arcade. It has been updated quite a bit since launch bringing in new modes and improvements. It recently launched on Nintendo Switch as well. | Read more »
Out Now: ‘Magic vs Metal’, ‘Suzerain’, ‘...
Each and every day new mobile games are hitting the App Store, and so each week we put together a big old list of all the best new releases of the past seven days. Back in the day the App Store would showcase the same games for a week, and then... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for December 7th, 2022. Today can be accurately described as Mikhail Madness, with a whopping four reviews from our pal-est of pals. Football Manager 2023 Touch, Wobbledogs, Soccer Story... | Read more »
Alchemy Stars celebrates 1 and a half ye...
It has been one and a half years since Alchemy Stars launched, and Level Infinite is celebrating in style with a host of new content. There will be a new story mission and even a store to explore, and a whole new mode for those budding idol... | Read more »
Fighting Game ‘Art of Fighting 2’ ACA Ne...
Last week, side-scrolling shooter Pulstar hit mobile platforms as the newest ACA NeoGeo series release from Hamster and SNK. Read Shaun’s review of it here. Today, fighting game Art of Fighting 2 has launched on iOS and Android. Art of Fighting 2... | Read more »

Price Scanner via MacPrices.net

New! Details on Verizon’s Christmas/Holiday p...
Verizon is offering discounts on iPhones, Apple Watch models, and iPads with specific promo codes as part of their Christmas/Holiday 2022 offerings. Codes are valid when adding a new line of service... Read more
Apple MagSafe accessories are back on Holiday...
Amazon has Apple MagSafe Chargers and Apple’s MagSafe Battery on sale for up to 24% off MSRP again as part of their Christmas/Holiday sale. Shipping is free, and all models are in stock: – MagSafe... Read more
13″ M2 MacBook Airs on sale again for the low...
Amazon has 13″ MacBook Airs with M2 CPUs in stock today and on sale for $150 off MSRP as part of their Christmas/Holiday Sale, prices start at $1049. Shipping is free. They are the lowest prices... Read more
Get an Apple 16″ MacBook Pro for $400 off MSR...
16″ MacBook Pros with Apple’s M1 Pro CPUs are in stock and on sale today at B&H Photo for $300-$400 off Apple’s MSRP for a limited time. Prices start at $2099 for M1 Pro models with 512GB or 1TB... Read more
Holiday clearance sale! Previous-generation A...
Amazon has 2nd generation 32GB and 64GB 4K Apple TVs with Siri remotes and 32GB Apple TV HDs on clearance sale for $80-$90 off original MSRP. Shipping is free, and delivery is available in time for... Read more
Christmas sale at Verizon: Apple AirPods Pro...
Verizon has first-generation Apple AirPods Pro on sale for $159.99 on their online store as part of their continuing Christmas/Holiday sale. Their price is $90 off Apple’s original MSRP, and it’s the... Read more
New Christmas/New Years promo at Xfinity Mobi...
Switch to Xfinity Mobile and open a new line of service, and take $400 off the price of a new iPhone, no trade-in required, through January 10, 2023. The $400 is applied to your account as credits... Read more
Apple iPad Smart Keyboard Folio prices drop u...
Apple iPad Smart Keyboard Folio prices have dropped up to $60 off MSRP at Amazon and Walmart as part of their Christmas/Holiday sales. These are the cheapest prices currently available for these iPad... Read more
Today is the final day for Xfinity Mobile’s $...
If you switch to Xfinity Mobile and open a new line of service, they will take $500 off the price of a new iPhone, no trade-in required. This is the best no trade-in Cyber Monday Apple iPhone 14 deal... Read more
Amazon restocks 10.2″ 64GB 9th-generation iPa...
Amazon has Apple’s 9th generation 10.2″ 64GB WiFi iPads (Silver) in stock and on sale for $269.99 shipped as part of their Christmas/Holiday Sale. Their price is $60 off Apple’s MSRP. Free delivery... Read more

Jobs Board

*Apple* Systems Administrator - JAMF - Activ...
…Administration **Duties and Responsibilities** + Configure and maintain the client's Apple Device Management (ADM) solution. The current solution is JAMF supporting 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
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
Sephora Beauty Advisor - *Apple* Blossom Ma...
Sephora Beauty Advisor - 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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.