Example of top-down design

Notice that the main function is complete. All other functions are stubbed out with an explanation of purpose, parameters, and return values. The interface of each function has been defined, i.e. how many and what types of parameters are expected as well as what will be returned. We have also placed temporary return values and function calls (optional, but helpful). Comments have been included inside the function definitions as reminders for how we expect to implement them.

An execution of this design in python shows us how the design looks at a high-level:

$ python3 stub-example.py 
In printIntro()
In getPositiveInteger()
In simulate()
In simulateOneTime()
In rollDice()
In rollOne()
The average is: 100.000000
The probability is: 0.010000

"""
 This program computes the probability of rolling five of a kind with
 six-sided dice by running a series of simulations and computing
 the average number of rolls required. 
"""

from random import *

def main():
    printIntro()
    numTrials = getPositiveInteger("Enter number of simulations to run: ")
    avg = simulate(numTrials)
    print("The average is: %f" % avg)
    print("The probability is: %f" % (1/avg))

# --------------------------------------------------------- #

def printIntro():
    """
    Parameters:  None
    Returns: None
    Purpose: To print an introduction to the user.
    """
    print("In printIntro()")
    return

# --------------------------------------------------------- #

def getPositiveInteger(prompt):
    """
    Parameters: A string prompt which is given to the user 
    Returns: A positive int value
    Purpose: To obtain a positive integer from the user 
          explained by the prompt.  The function repeats the 
          a prompt until a proper value is entered
    """
    print("In getPositiveInteger()")
    return 1

# --------------------------------------------------------- #

def simulate(n):
    """
    Parameters:  An integer n representing the number of simulations to run.
    Returns: A float representing the average number of rolls required
             to get five of a kind.
    Purpose: Simulate n trials of rolling dice and compute the average.
    """
    print("In simulate()")
    # will call simulateOneTime n times
    numrolls = simulateOneTime()
    return 100.0

# --------------------------------------------------------- #

def simulateOneTime():
    """
    Parameters:  None
    Returns: An integer representing the number of rolls required to
             get five of a kind.
    Purpose: Simulate one trial and count the number of rolls.
    """
    print("In simulateOneTime()")
    # will call rollDice until the result is allSame
    rolls = rollDice(5)
    return 100

# --------------------------------------------------------- #

def rollDice(n):
    """
    Parameters:  An integer n representing the number of dice to roll.
    Returns: A list containing the dice rolls of length n.
    Purpose: Randomly roll n dice. 
    """
    print("In rollDice()")
    # will call rollOne n times
    roll = rollOne()
    return [1] * n

# --------------------------------------------------------- #

def allSame(ls):
    """
    Parameters:  A list of values.
    Returns: True if all the values in the list are the same.
             Otherwise False.
    Purpose: Checks whether the values in a list are equal.
    """
    print("In allSame()")
    return True

# --------------------------------------------------------- #

def rollOne():
    """
    Parameters:  None
    Returns: An integer representing the die value between 1 and 6.
    Purpose: Randomly roll one die.
    """
    print("In rollOne()")
    # will use the random library to simulate a die roll
    return 1

# --------------------------------------------------------- #

main()