By the end of this lesson, cadets will be able to:

1. Decompose a problem statement into program modules and functions. (Outcomes 3, 7)
2. Design header files that expose appropriate interfaces. (Outcome 7)
3. Document design decisions in a written design artifact. (Outcomes 4, 7)

Complete before class. These set the vocabulary we will use.

Slides

Lesson 23 slide deck (PDF)

Why this lesson exists

On every lab so far, the spec told you what functions to write. You implemented prototypes that someone else (your instructor) decided on. That work was important, but it skipped the question every real C developer asks first: how did you decide the program should look like THIS?

Today is the lesson where that question gets a process and a vocabulary. You have been doing the underlying skill all semester. At Lesson 6 you refactored a monolithic main into functions you named. At Lesson 19 you designed structs around the data they hold. At Lesson 20 you decided what belongs in a header. Each of those was decomposition in disguise. Lesson 23 is where it gets a name.

The lab is the rehearsal for your Team PEX design check-in. The widget walks you through a small example. The lab takes you through one yourself, with a written deliverable.

The four-step process

A repeatable way to go from a written requirements document to a sketch of the program:

1. Read and underline. Read the requirements once for understanding. Read again with two colored pens: one for nouns (the data the program holds), one for verbs (the actions the program performs). Anything underlined twice is interesting.
2. Group nouns and verbs into modules. Verbs that act on the same noun belong together. Nouns that the program owns end to end deserve their own type. A module is one or more verbs operating on a related set of nouns.
3. Sketch the interfaces. For each module, write a header file. Function signatures. Comments that say what the function does, what the inputs mean, what the output means, and who owns any memory returned. Skip implementation.
4. Document and check. Write a short memo explaining the choices. Then ask: if I hand this to a teammate, what is the first question they ask? Whatever it is, your memo should already answer it.

The widget in Section 5 walks you through every step on a small flashcard-study example before you tackle the lab.

What belongs in a header

A header is a contract. Anything you put in it is a public promise to the rest of the codebase. The smaller and more honest the header, the easier the program is to maintain.

Put in the header:

• The header guard (Lesson 20).
• Type declarations that callers need: typedef, enum, struct forward declarations.
• Function prototypes that other files will call.
• A function header block above each prototype (DFCS §2.2) explaining what it does, what each parameter means, what it returns, and who owns any returned memory.

Keep OUT of the header:

• Anything declared static. It is internal by design.
• Function implementations.
• Variable definitions (declarations are fine when truly needed, with extern; this is rare).

Ownership lives in the interface

Any function that returns a pointer is making a statement about ownership. The header is where that statement gets written down. Three patterns cover most cases:

• Allocator pattern. Function returns a heap pointer; caller must free it (or call a matching destructor). load_deck above is one. malloc, strdup, fopen are standard library examples.
• Borrow pattern. Function returns a pointer INTO existing memory (a string inside a struct, a card inside a deck). Caller must not free; the pointer becomes invalid when the underlying object goes away.
• Out-parameter pattern. Function takes a pointer to caller-allocated storage and writes through it. No allocation, no ownership transfer.

The doc comment on the header is where the pattern gets named. If a teammate has to guess, the header is wrong. This is exactly the DFCS §8.5 discipline: every malloc has a matching free, and the design says who calls each.

The design memo

The third deliverable today is a short written memo, about one page, that captures your design choices in prose. The lab template gives you a structure to fill in. The required sections:

• Modules. Each module gets a one-sentence purpose statement.
• Data structures. The types you defined and why.
• Ownership notes. Who allocates, who frees, what borrows from what.
• How will we test this? One concrete test case per function in your interface.
• Open questions. What you would ask the customer if you had more time.

The testing section is not an afterthought. If you cannot name a test case for a function, your interface is underspecified: the function has no observable result, or the inputs are not well defined. Change the design before you write code.

DFCS C Programming Standard touchpoint

Today touches two sections of the standard:

• §2.2 Function Header Block. Every prototype in a header carries a documented function header block: purpose, parameters, return value, and (today\'s addition) ownership of any pointer returned.
• §8.5 Always free dynamically allocated memory. The standard is short ("free what you allocate"). The design discipline is longer: the header names who allocates and who frees, so by the time you implement, the ownership rules are already on paper.

See the Resources section for the full standard text.

• Opener: Kahoot retrieval (10 min). Quick review of L20 multi-file rules and L22 argv discipline before today\'s content.
• Decompose walkthrough (25 min). Twelve guided design decisions on the flashcard-study spec. Below.
• Interface design self-check (10 min). Eight questions on header design, visibility, ownership. Below.
• Lab: Design a Wordle module (60 min). Read the requirements, produce wordle.h, DESIGN.md, and a skeleton main. GitHub Classroom assignment.
• Submit Team PEX topic proposal (15 min). Teams finalize and submit their topic choice via the Blackboard PEX Proposal assignment.

Decompose Walkthrough

Twelve design decisions on a small flashcard-study spec. Read the spec in the right pane, then answer each prompt. The right pane records your decisions as you go.

Interface Design Self-Check

Eight questions on header design, module boundaries, and ownership. Pass at 70% or above; below that, take it again after reviewing.

• Submit Lab 23 (wordle.h + DESIGN.md + main_skeleton.c) through GitHub Classroom before Lesson 24.
• Submit the Lesson 23 reflection in Blackboard. Include the completion codes from both widgets and your screenshot.
• Confirm your team\'s Team PEX topic proposal was submitted today. The design check-in is due at Lesson 26; today\'s lab is the rehearsal for that work at team scale.
• Read for Lesson 24 (Git in Depth I): Beej-Git §4-6 on branching, merging, and conflict resolution.
• Heads up: GR3 at Lesson 28 covers Block 3 content. Software design questions ARE fair game.