A solution to over or under-coding
Example 1 – IPO Chart
Input |
Processing |
Output |
Data In Name Address Phone Number |
Algorithm GET name, address, phone number QUERY database for record matching the information IF query is successful THEN GET receipt from database ELSE ALERT user of error END IF DISPLAY receipt |
Information Out Client’s Receipt |
The table format isn’t for everyone. It suffices as a program summary, but a design document is more robust and will help us in the long-run.
Problem
The problem to solve, normally in plain English. May include descriptions of inputs, outputs and processing, or it may hint on these. Don’t dive into code with “thereabouts” – computer programs are exact.
Input
List your inputs – the incoming data which will be processed to produce output. Include only inputs specific to the problem.
Ex: Don’t include intrinsic functions/data types – if you know your development environment has native support for something, just mention it in your algorithm.
Assumptions
This is probably the biggest time saver of all. This is where we resolve hints and thereabouts into tangible specifications. Will you assume everything’s properly formatted? If not, how will you resolve this? Your assumptions specify what your code can or can’t handle.
Output
High Level Tasks
Tasks performed when turning input into output; a logical summary of your algorithm. There may be one or multiple tasks, depending on what you consider important enough for mention.
Pseudocode (Algorithm)
I often use split view/multiple windows to view my program’s specifications, algorithm and source code all at once.
Example 2 – Simple Design Document
Problem A hotel wants an application to calculate the bill for a guest. Guests are charged based on nights stayed and nightly rate. They are also charged for room service, phone use and miscellaneous charges. Display a bill depicting total cost of bed, total service costs, taxes and total costs. Input Nights stayed, nightly rate, phone charge, room service charge, misc charge, tax rate Assumptions · All data are numbers. We’re throwing an exception if otherwise. · Taxes are given as an input – tax rate. · Total cost is equivalent to net costs, the sum of total cost of bed, total service costs and taxes. Output Total room cost, total service costs, total taxes and total costs High Level Tasks
Pseudocode (Algorithm – generally on a separate page) GET # nights, nightly rate, phone cost, room service cost, misc cost, tax rate Total room cost = # nights * nightly rate Total service cost = phone cost + room service cost + misc cost Total gross cost = (Total room cost + Total service cost) Taxes = (Total gross cost * tax rate) Total net cost = Total gross cost + Taxes DISPLAY Total room cost, Total service cost, Total taxes, Total net cost |
It seems like a pretty simple program. Why did this document save so much time?
Making assumptions allows us to simply our algorithm – assuming all input is numerical us to simply throw an exception if otherwise. We don’t have to worry about parsing currency.
Stating our inputs and outputs makes developing the algorithm much easier and straight-forward. It also give us an idea of what the program will look like as a visual application, or how to format the bill/receipt.
Considering high-level tasks also made developing the algorithm simpler, because we already knew our inputs/outputs.
We’ve considered the what-ifs before we begin coding so we don’t face them in the middle of coding. Killing bugs eventually costs a lot more time than anticipating them. It’s not magic. It’s just good design.