# 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:

```\$ python 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.

Author: Sally CS Major
Date: Spring 2011
"""

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()")
# will check that each value is equal to the first value

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()
```