Chapter Introduction and Learning Objectives

Learning Objectives

By the end of this chapter, you should be able to:

1. 1Identify the qualities of a well-scoped beginner Python project.
2. 2Write clear functional and non-functional requirements for a program.
3. 3Design a central data structure and a function table before writing code.
4. 4Use milestones and stub functions to build a program in stages while keeping it runnable at every step.
5. 5Design and run deliberate test cases for individual functions and for the complete program.
6. 6Refactor working code for clarity, consistency, and robustness.
7. 7Write docstrings, inline comments, and a README that make a project understandable to others.
8. 8Present a completed project by demonstrating its features, explaining its organization, and describing a problem that was solved during development.

Sections at a Glance

• 30.1What Makes a Good Beginner Python ProjectFive qualities of a well-chosen capstone project; the difference between a learning goal and a program purpose; common beginner project mistakes
• 30.2Choosing a ProjectThree questions to ask before choosing; scoping for available time; why you need a clear description before writing code; common mistakes in project selection
• 30.3Writing RequirementsFunctional requirements; non-functional requirements; worked example: Personal Study Tracker; writing requirements as testable statements
• 30.4Planning MilestonesWhy milestones matter; the milestone pattern; worked example milestone table; building so you always have runnable code
• 30.5Designing Data and Program FlowDesigning the central data structure; designing program flow as numbered steps; designing a function table before implementation
• 30.6Building the First Working VersionStarting with the core data structure; building function by function; stub functions; the menu loop; the main block with __name__
• 30.7Testing and Debugging the ProjectTesting individual functions; designing test case tables; edge cases and invalid inputs; testing file saving and loading; regression testing
• 30.8Improving and RefactoringCompleting stub functions; save and load with csv; refactoring for clarity; what not to over-engineer
• 30.9Writing DocumentationThree levels of documentation: docstrings, inline comments, and README; sample README structure; why documentation forces clarity
• 30.10Presenting the ProjectFive areas of a good project presentation; presenting code to an audience; submission checklist
• 30.11Reflecting on Growth as a ProgrammerComparing early programs to the capstone; the habits of a careful programmer; directions for further study

What Makes a Good Beginner Python Project

Choosing a Project

Writing Requirements

Planning Milestones

Worked Example: Study Tracker Milestone Table

Designing Data and Program Flow

Designing Your Data

# A single session as a dictionary
session = {
    "subject": "Mathematics",
    "minutes": 45,
    "note": "Practiced integration by parts",
    "date": "2025-09-14"
}

# All sessions together are a list of these dictionaries
sessions = [
    {"subject": "Mathematics", "minutes": 45, "note": "...", "date": "2025-09-14"},
    {"subject": "Python",      "minutes": 60, "note": "...", "date": "2025-09-14"},
    {"subject": "Mathematics", "minutes": 30, "note": "...", "date": "2025-09-15"}
]

Designing Your Program Flow

Designing Your Functions

Building the First Working Version

Start With the Data Structure

def add_session(sessions, subject, minutes, note=""):
    """Add a new study session to the sessions list."""
    from datetime import date
    session = {
        "subject": subject,
        "minutes": minutes,
        "note": note,
        "date": str(date.today())
    }
    sessions.append(session)
    return sessions


# Quick test — run this before adding anything else
sessions = []
sessions = add_session(sessions, "Mathematics", 45, "Integration practice")
sessions = add_session(sessions, "Python", 60, "Working on capstone")
print(sessions)

Stub Functions

def get_valid_minutes():
    """Prompt user until a valid positive integer is entered."""
    return 30  # Stub: always returns 30 for now


def show_subject_sessions(sessions, subject):
    """Print all sessions for a given subject."""
    print("(Not yet implemented)\n")  # Stub


def show_recent_sessions(sessions, n=5):
    """Print the most recent n sessions."""
    print("(Not yet implemented)\n")  # Stub


def save_sessions(sessions, filename):
    """Save sessions to a CSV file."""
    print(f"(Stub: would save {len(sessions)} sessions to {filename})\n")


def load_sessions(filename):
    """Load sessions from a CSV file."""
    return []  # Stub: always returns empty list

The Main Block

if __name__ == "__main__":
    sessions = load_sessions("study_sessions.csv")
    run_menu(sessions)

Testing and Debugging the Project

Test Each Function Alone First

# Test add_session
sessions = []
sessions = add_session(sessions, "History", 30, "Read chapter 4")
assert len(sessions) == 1
assert sessions[0]["subject"] == "History"
assert sessions[0]["minutes"] == 30
print("add_session: PASSED")

# Test show_summary with known data
sessions = []
sessions = add_session(sessions, "History", 30)
sessions = add_session(sessions, "History", 45)
sessions = add_session(sessions, "Python", 60)
# Expected: History = 75 minutes, Python = 60 minutes
show_summary(sessions)
# Read the output and verify manually

Design Test Cases With Intention

Testing File Saving and Loading

Improving and Refactoring

Complete: get_valid_minutes

def get_valid_minutes():
    """Prompt the user until a valid positive integer is entered.

    Returns:
        int: A positive number of minutes.
    """
    while True:
        raw = input("Minutes studied: ").strip()
        try:
            minutes = int(raw)
            if minutes <= 0:
                print("Please enter a positive number of minutes.")
                continue
            return minutes
        except ValueError:
            print("Please enter a whole number.")

Complete: save_sessions and load_sessions

import csv


def save_sessions(sessions, filename):
    """Save all sessions to a CSV file.

    Args:
        sessions (list): The list of session dictionaries to save.
        filename (str): Path to the output CSV file.
    """
    fieldnames = ["subject", "minutes", "note", "date"]
    try:
        with open(filename, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=fieldnames)
            writer.writeheader()
            writer.writerows(sessions)
    except OSError as e:
        print(f"Error saving sessions: {e}")


def load_sessions(filename):
    """Load sessions from a CSV file.

    Args:
        filename (str): Path to the CSV file to load.

    Returns:
        list: A list of session dictionaries, or an empty list if file not found.
    """
    sessions = []
    try:
        with open(filename, newline="", encoding="utf-8") as f:
            reader = csv.DictReader(f)
            for row in reader:
                row["minutes"] = int(row["minutes"])  # CSV stores strings
                sessions.append(row)
    except FileNotFoundError:
        pass  # Normal on first run
    except OSError as e:
        print(f"Error loading sessions: {e}")
    return sessions

Refactoring Opportunities to Look For

Writing Documentation

Level 1: Docstrings

def add_session(sessions, subject, minutes, note=""):
    """Add a new study session to the sessions list.

    Args:
        sessions (list): The existing list of session dictionaries.
        subject (str): The name of the subject studied.
        minutes (int): The number of minutes spent studying.
        note (str): An optional note about the session. Defaults to "".

    Returns:
        list: The sessions list with the new session appended.
    """
    from datetime import date
    session = {
        "subject": subject,
        "minutes": minutes,
        "note": note,
        "date": str(date.today())
    }
    sessions.append(session)
    return sessions

Level 2: Inline Comments

# Good: explains why, not what
recent.reverse()  # Most recent sessions should appear first
row["minutes"] = int(row["minutes"])  # CSV stores all values as strings

# Bad: restates the code with no added meaning
count += 1  # Add 1 to count

Level 3: README File

Presenting the Project

Tips for Presenting Code

Reflecting on Growth as a Programmer

The Habits You Have Built

What Comes Next

Chapter Summary

• Section 30.1A good beginner project solves a real problem, is within reach, combines multiple skills, can grow, and can be explained. A focused working program is more impressive than an ambitious broken one.
• Section 30.2Choose a project by asking what problem you care about, how much time you have, and whether you can describe the program in plain language before writing code. Avoid projects requiring unfamiliar external packages or graphical interfaces.
• Section 30.3Requirements are plain-language statements of what a program must do. Functional requirements describe what the user can do. Non-functional requirements describe how the program behaves. Write requirements as a checklist to test against.
• Section 30.4Milestones keep you always working from a runnable version. A five-milestone pattern — core data, working menu, all features in memory, file persistence, polish — fits most beginner projects.
• Section 30.5Design your central data structure, describe your program flow in numbered steps, and list all planned functions in a table before writing implementation code.
• Section 30.6Start with the data structure and one function. Build upward using stub functions that let you run the program before every feature is complete. Always protect the main block with if __name__ == "__main__":.
• Section 30.7Test each function alone with explicit test cases before testing the full program. Design test cases covering normal inputs, edge cases, and invalid inputs. Test file saving and loading explicitly. Re-run tests after every change.
• Section 30.8Complete stub functions with real implementations. Refactor for readability, clear variable names, and stronger error messages. Avoid premature optimization — finish the program you planned.
• Section 30.9Document at three levels: docstrings on every function, inline comments explaining non-obvious logic, and a README file describing the project to outside readers. Writing documentation forces clarity in the code itself.
• Section 30.10A good presentation covers what the program does, how it is organized, one function you are proud of, one problem you solved, and what you would improve next. Explain why, not just what.
• Section 30.11The habits developed in this course — reading code, designing before coding, testing intentionally, debugging systematically, writing clearly — transfer across every language and project you will encounter next.

Key Terms

Use this template before you write a single line of Python. Fill it in on paper or in a text file.

Project Title:

One-sentence description:

Functional Requirements:
1.
2.
3.
4.
5.

Non-Functional Requirements:
1.
2.
3.

Central Data Structure (plain language, then sketch as Python):


Function List:
| Function Name | Parameters | Returns | Job |
|---------------|------------|---------|-----|
|               |            |         |     |

Program Flow (numbered steps):
1.
2.
3.
...

Milestone Plan:
| Milestone | Goal | Done When |
|-----------|------|-----------|
| 1         |      |           |
| 2         |      |           |
| 3         |      |           |
| 4         |      |           |
| 5         |      |           |

Choose one project appropriate to your available time and interest. Build the core scope first — extend only after it works.

These questions draw on skills from across the entire textbook. Suitable for final exam preparation, independent review, or instructor-assigned exercises.

Vocabulary Review

1. What is the difference between a syntax error and a logic error?
2. What does a function's return value mean? How is it different from printing?
3. What is scope? Why do local variables not exist outside their function?
4. What is the difference between a list and a dictionary?
5. What does the with statement do when opening a file?
6. What is an exception? What does try and except do?
7. What is a class? What is an instance?
8. What does it mean to refactor code?
9. What is a docstring? Why should every function have one?
10. What is a milestone in project development?

Code Reading

Read each program carefully and answer the question below it.

data = [12, 7, 19, 3, 15]
result = 0
for value in data:
    if value > 10:
        result += value
print(result)

What does this program print? What would you rename result to better describe what it holds?

def mystery(text):
    count = 0
    for char in text:
        if char in "aeiouAEIOU":
            count += 1
    return count

print(mystery("Programming"))
print(mystery("Python"))

What does mystery do? What is a better name for it? What does it print?

records = [
    {"name": "Alice", "score": 88},
    {"name": "Bob",   "score": 74},
    {"name": "Carol", "score": 95}
]

for record in records:
    if record["score"] >= 90:
        print(record["name"], "passed with distinction")
    elif record["score"] >= 75:
        print(record["name"], "passed")
    else:
        print(record["name"], "did not pass")

What does this program print? What would happen if the list were empty?

def load_data(filename):
    items = []
    try:
        with open(filename) as f:
            for line in f:
                items.append(line.strip())
    except FileNotFoundError:
        pass
    return items

What does this function return if the file exists? What does it return if the file does not exist? Why is pass used in the except block?

Debugging Practice

Each code sample contains at least one error. Identify the error and write a corrected version.

def total(numbers)
    result = 0
    for n in numbers:
        result += n
    return result

scores = [85, 90, 78, 92]
average = sum(scores) / len(scores)
print("Average: " + average)

result = is_passing(75)
if result = True:
    print("Passing")

counts = {}
words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
for word in words:
    counts[word] = counts[word] + 1
print(counts)

Short Programming Tasks

1. Write a function clean_name(name) that takes a string, strips whitespace from both ends, and returns the name with the first letter of each word capitalized.
2. Write a function find_above_average(numbers) that takes a list of numbers and returns a new list containing only the values above the average. If the list is empty, return an empty list.
3. Write a function count_by_category(items) that takes a list of dictionaries, each with a "category" key, and returns a dictionary mapping each category to the number of items in it.
4. Write a function safe_divide(a, b) that returns the result of a / b but returns None if b is zero. Write three test calls demonstrating normal use, zero division, and using the result in a print statement.
5. Write a function load_words(filename) that reads a text file where each line is one word, and returns a list of those words with whitespace stripped. If the file is not found, print a message and return an empty list.

Write answers to these questions in your notebook or study journal before moving on.

1. What was the hardest concept in this course for you? What helped you understand it?
2. Describe a program you wrote that did not work the first time. How did you figure out what was wrong?
3. What is the most useful Python skill you learned? Why?
4. What do you wish you had understood earlier in the course that would have helped you?
5. What kind of programs do you want to build next? What skills would you need to learn to build them?
6. Compare how you thought about programming at the beginning of the course to how you think about it now. What has changed?

Course Completion Review

You have completed Programming with Python. Here is every major skill developed across all seven parts.