A solution to over or under-coding
Programmers in our community and in many others (such as GameDev) suffer the problem of over- or under-designing/coding their applications. They waste a lot of time hacking around, spending countless hours trying to find solutions to fairly trivial problems. One way to avoid this is to use IPO Charts and the (dreaded) design document. I’ll explain both and demonstrate how the latter is actually a time saver when formatted properly.IPO stands for Input, Processing and Output. IPO Charts are a simple tool that programmers use to summarize their programs for personal use, sharing programs or describing them to clients. IPO Charts typically appear as follows:
Example 1 – IPO Chart
GET name, address, phone number
QUERY database for record matching the information
IF query is successful THEN
GET receipt from database
ALERT user of error
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.
Don’t be scared of the words “design document” just because a lot of bad programmers have written huge ones with no code. Our goal is to save time and improve effectiveness, so we’re going to consider the simplest set of information necessary to write a robust program.
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.
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.
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.
Ex: Imagine accepting currency without a currency parser. You can either get/make one or support only numeric input. Without considering this, you could have run into a huge mess once testing began.
Thinking about your assumptions lets you handle all of these potential problems while you’re still “designing” your program, rather than in the middle of or after initial development.
Processed data, or information, your program will produce. Be as specific or vague as need be.
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.
The processing part of IPO.
Having a separate section/page for your algorithm gives you more room and a separate space to think.
I often use split view/multiple windows to view my program’s specifications, algorithm and source code all at once.
Here’s a design document I wrote up (and was thankful for) just recently.
Example 2 – Simple Design Document
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.
Nights stayed, nightly rate, phone charge, room service charge, misc charge, tax rate
· 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.
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.
Consider the development of an application to be an algorithm in itself. As always, we’re looking for the most efficient one. Let’s think about another bad subject for us programmers – hacking around.
What is the “hacking around” worst-case scenario? Hours, days, sometimes weeks of poking around hoping the next line of code you write is the right one.
The research worst-case scenario? Discovering there isn’t a lot of information on the topic you’re looking up and having to develop a solution yourself. You might be surprised to find that this doesn’t happen often, and when it does, you can simply write a design document