top-down design

motivation

As we write bigger and more complex programs, designing them first will save time in the long run. Similar to writing an outline for a paper, using top-down design means we write out main() first, using functions we assume will work (and that we will write, later). We also decide on any data structures we will need.

What we want to avoid is writing a whole bunch of functions and code, and then realizing we forgot something, which changes some of the functions, which changes other functions, and so on.

Furthermore, we want a way to test each function as we write it. Many first-time programmers will write lots of functions and then start testing them. If each function has a few bugs in it, this makes it a lot harder to debug.

syntax

A typical top-down design includes the following:

main() all written out
function stubs written (def with params, function comment, dummy return value)
data structures clearly defined (store data in a list? an object? a list of objects? something else?)
the design should run without any syntax errors
running the design should show how the program will eventually work

Once you have the design all written out, you can now attack each function one-at-a-time. Get the function to work. Test it to make sure it works, then move on to the next function.

examples

Imagine you want to write a terminal-based tic-tac-toe game. Here's what the (klunky) program might look like:

$ python tictactoe.py 

   0 | 1 | 2
  -----------
   3 | 4 | 5
  -----------
   6 | 7 | 8


     |   |  
  -----------
     |   |  
  -----------
   o |   |  

your turn (0-8): 0

   x |   |  
  -----------
     |   |  
  -----------
   o |   |  


   x |   |  
  -----------
     |   |  
  -----------
   o |   | o

your turn (0-8): 1

   x | x |  
  -----------
     |   |  
  -----------
   o |   | o


   x | x |  
  -----------
     | o |  
  -----------
   o |   | o

your turn (0-8): 2

   x | x | x
  -----------
     | o |  
  -----------
   o |   | o

X WINS!!

And here's a sample design for that game:

"""
design for tic-tac-toe

currently doesn't do much, but there are no syntax errors, main()
is written, and function stubs are written. Now we can work on each
function ONE-at-a-time.

J. Knerr
Spring 2017
"""

from random import *

def main():
  board = list("         ")   # 9-item list of " " chars
  turn = choice(["user","comp"])
  while True:
    display(board)
    if turn == "user":
      userTurn(board)
      turn = "comp"
    else:
      compTurn(board)
      turn = "user"
    result = checkGameOver(board)
    if result == True:
      break

def checkGameOver(board):
  """return True if game over, also print the results"""
  return False

def compTurn(board):
  """computer chooses a location on the board"""
  index = randrange(0,9)
  print(index)
  board[index] = "o"

def userTurn(board):
  """ask user for location, make sure it's valid, mark the board"""
  position = int(raw_input("0-8: "))
  board[position] = "x"

def display(board):
  """display list as a tic-tac-toe board"""
  print(board)

###########################################
main()

your turn

Imagine you want to write a flashcard program, that reads some flashcard data from a file, then quizzes the user on the flashcard data. Here's an example:

$ python fc.py 
         essen: to eat
        kaufen: to buy
      besuchen: to think
Nope...besuchen = to visit
        fahren: to travel
        lieben: to love
      schlafen: to sleep
       spielen: to run
Nope...spielen = to play
       trinken: to drink
     verstehen: to understand
==============================

Number correct: 7  (out of 9)
Not bad.

If we have the flashcard data in a file called "german.txt", can you write a design for the flashcard program?

$ cat german.txt 
essen:to eat
kaufen:to buy
besuchen:to visit
fahren:to travel
lieben:to love
schlafen:to sleep
spielen:to play
trinken:to drink
verstehen:to understand

CS21 Topics