Developing a New Program¶

Throughout Deepest Dungeon, each stage came with a plan: pseudocode, a class diagram and the code to build. That got us a working game, but when we start our own program, nobody hands us the plan. We need to figure it out ourselves.

So in this guide we'll go through the same process we used in the stages, but from the very start. We'll use a small example, a pet shelter program, so we can see each part of the process in action.

The process has four parts:

1. Define the problem.
2. Design the solution.
3. Build it in small stages.
4. Test and evaluate it.

1. Define the problem¶

Before we write any code, we need to be clear about what our program has to do. If we don't know where we're going, we won't know when we've got there. So we start by writing a list of requirements. These are short statements of what the program must do, written so we can test them later.

Our pet shelter wants a program that lets visitors see the animals and adopt one. So the requirements are:

2. Design the solution¶

Find the classes¶

Now that we know what the program needs to do, we need to figure out which classes we need. A simple way to start is to look for the nouns in the requirements: pet, dog, cat, shelter and visitor. Each of these could be a class, so let's think about each one:

• pet → holds the details of one animal → Pet class
• dog and cat → kinds of pet that make different sounds → child classes of Pet
• shelter → holds all the pets and lets visitors adopt them → Shelter class
• visitor → the person using the program → handled by main.py, not a class

Find the attributes and methods¶

Next, we work out what each class needs to know and what it needs to do. Remember from the OOP Primer:

• things an object knows → attributes (like a pet's name and age)
• things an object does → methods (like listing pets or adopting one)

The verbs in the requirements (list, adopt, make a sound) give us a good idea of the methods we need. Putting it all together, our design looks like this:

This table holds the same information as the three rows of a UML class diagram, like the ones we used in the stages. Draw it as a class diagram for your own program, so you can check your design before you write any code.

Plan the steps¶

Finally, we plan the order we'll build things in. Just like the stages, each step should give us something we can run and test, so we write the plan as pseudocode.

- Define the Pet class with a describe method
- Define the Shelter class, add pets and list them
- Add Dog and Cat child classes that speak differently
- Add adopting, and a main loop that responds to commands

3. Build in small stages¶

Now that we have a plan, let's build it. We'll work through the pseudocode one step at a time, and run the program after each step. This makes it easier to test as we go, and if something breaks, we know it's in the code we just added.

Step 1: the Pet class¶

Create a new folder for the project. Then create a new file in Thonny, add the code below and save it as pet.py.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# pet.py

class Pet():

    def __init__(self, name, age):
        # initialises the pet object
        self.name = name
        self.age = age
        self.adopted = False

    def describe(self):
        # displays the pet's details
        print(f"{self.name} is {self.age} years old.")

Step 2: the Shelter class¶

Create a new file, add the code below and save it as shelter.py.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# shelter.py

class Shelter():

    def __init__(self, name):
        # initialises the shelter object
        self.name = name
        self.pets = []

    def add_pet(self, pet):
        # adds a pet to the shelter
        self.pets.append(pet)

    def list_pets(self):
        # displays every pet that hasn't been adopted
        print(f"\nPets at {self.name}:")
        for pet in self.pets:
            if not pet.adopted:
                pet.describe()

Now we need main.py to test both classes. Create it with the code below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# main.py

from pet import Pet
from shelter import Shelter

# create shelter
shelter = Shelter("Happy Paws")

# add pets
shelter.add_pet(Pet("Rex", 3))
shelter.add_pet(Pet("Mittens", 2))

shelter.list_pets()

Step 3: Dog and Cat¶

Requirement R3 says dogs and cats make different sounds. So this is a job for inheritance and polymorphism, just like the Friend and Enemy classes in Stage 4. Go back to pet.py and add the highlighted code below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# pet.py

class Pet():

    def __init__(self, name, age):
        # initialises the pet object
        self.name = name
        self.age = age
        self.adopted = False

    def describe(self):
        # displays the pet's details
        print(f"{self.name} is {self.age} years old.")

    def speak(self):
        # the pet makes a sound
        print(f"{self.name} doesn't make a sound.")


class Dog(Pet):

    def speak(self):
        # the dog makes its sound
        print(f"{self.name} says Woof!")


class Cat(Pet):

    def speak(self):
        # the cat makes its sound
        print(f"{self.name} says Meow!")

Then go to main.py and change the highlighted code, so we create a dog and a cat and test their sounds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# main.py

from pet import Dog, Cat
from shelter import Shelter

# create shelter
shelter = Shelter("Happy Paws")

# add pets
shelter.add_pet(Dog("Rex", 3))
shelter.add_pet(Cat("Mittens", 2))

shelter.list_pets()

# test the sounds
for pet in shelter.pets:
    pet.speak()

Step 4: adopting and the main loop¶

Now let's add adopting (requirement R4). Return to shelter.py and add the highlighted method below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# shelter.py

class Shelter():

    def __init__(self, name):
        # initialises the shelter object
        self.name = name
        self.pets = []

    def add_pet(self, pet):
        # adds a pet to the shelter
        self.pets.append(pet)

    def list_pets(self):
        # displays every pet that hasn't been adopted
        print(f"\nPets at {self.name}:")
        for pet in self.pets:
            if not pet.adopted:
                pet.describe()

    def adopt(self, pet_name):
        # adopts the pet with the given name, if it's available
        for pet in self.pets:
            if pet.name.lower() == pet_name.lower() and not pet.adopted:
                pet.adopted = True
                return pet
        return None

Finally, we need a way for the visitor to use the program. Return to main.py and replace the test code with a main loop, like the one we built in Stage 2.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# main.py

from pet import Dog, Cat
from shelter import Shelter

# create shelter
shelter = Shelter("Happy Paws")

# add pets
shelter.add_pet(Dog("Rex", 3))
shelter.add_pet(Cat("Mittens", 2))
shelter.add_pet(Dog("Biscuit", 5))

# ----- MAIN LOOP -----
running = True
while running:
    command = input("\nlist, adopt or quit? > ").lower()

    if command == "list":
        shelter.list_pets()
    elif command == "adopt":
        choice = input("Which pet? > ")
        pet = shelter.adopt(choice)
        if pet:
            print(f"You adopted {pet.name}!")
            pet.speak()
        else:
            print(f"{choice} isn't available.")
    elif command == "quit":
        running = False
    else:
        print("Please type list, adopt or quit.")

print("Thanks for visiting Happy Paws.")

4. Test and evaluate¶

Test¶

Just like in the stages, we need to test every branch of our code. So let's draw up a testing table. Run each test and fill in the actual results.

If any actual result doesn't match its expected result, we've got a bug. Use the debugger to track it down.

Evaluate¶

Testing tells us whether the code works, but that's not the whole story. We also need to check that the program does what it was meant to do. This is called evaluating. So we go back to our requirements, and check each one against our test results.

Evaluating is also a good time to think about what could be better. For example, the shelter can't take in new pets while the program is running, and the visitor can't tell whether a pet is a dog or a cat. These would make good features for the next version.

Your turn¶

Now it's your turn to use the same process for your own program. Work through this checklist as you go:

1. I've written my requirements as a numbered list of testable statements.
2. I've found my classes from the nouns, and my methods from the verbs.
3. I've drawn a class diagram (or table) with every class's attributes and methods.
4. I've written pseudocode that splits the build into small steps.
5. I've run and tested my program after every step.
6. I've completed a testing table that covers every branch.
7. I've evaluated my program against each requirement, and noted improvements.