Creating a Program Specification
A useful test is: Do I know enough about the inputs, outputs, rules, limits, and special cases to describe the program's behavior? If not, the problem is still in analysis rather than design.
Before Coding
A problem statement can sound simple while still leaving too many important decisions unanswered. Problem analysis is the process of identifying those gaps and ambiguities before you begin coding. Its purpose is not to solve the problem immediately. Its purpose is to understand what the program must do, what decisions must be made, and what rules the program must follow.
Tracing the Missing Details
Consider the request to write a program that backs up important files. The basic action appears to be copying files from one place to another, but the request does not define which files are important, where the backup should go, whether existing backups should be overwritten, or whether multiple versions should be kept. Each unanswered question could change the program's behavior.
A useful test is: Do I know enough about the inputs, outputs, rules, limits, and special cases to describe the program's behavior? If not, the problem is still in analysis rather than design.
Analysis Before Design
Problem analysis identifies what is missing or unclear in the statement. You examine the decisions that must be made and ask questions to obtain the necessary information. The key decision is whether the statement contains enough information to move forward. If it does not, you seek clarification. If it does, you use the answers to create a design.
| Analysis question | What it clarifies |
|---|---|
| Which files should be backed up? | The program's selection rule |
| Where should the backup go? | The program's destination |
| Should existing backups be overwritten? | The program's handling of existing data |
| Should multiple versions be kept? | The program's version behavior |
Questions turn an incomplete request into decisions that can be used during design.
Turning Answers into Requirements
Program design begins after analysis has supplied enough answers. Design converts those answers into a functional requirements list: a concrete description of how the program should behave. A requirement should state an observable behavior, such as what the program accepts, what it processes, and where it stores its result.
Specifying the backup program
Turn the backup request into a small functional requirements list using the decisions supplied during analysis.
- 1Define the input
The program will accept a folder path as input.
- 2Define the files
The program will back up all files in that folder.
- 3Define the destination
The backup will be saved to a folder named backups_YYYY-MM-DD in the user's home directory.
- 4Record remaining decisions
The treatment of existing backups and whether multiple versions are kept must also be specified if those decisions are required for the program's behavior.
The analysis has become a functional requirements list that can guide coding. It states the input, the files to process, and the backup destination instead of leaving those choices implicit.
When Design Reveals More Questions
Analysis and design are not always a straight line. You may believe that the problem is clear, begin writing the requirements, and then discover another unanswered question. For example, deciding how to store a backup may expose an unresolved decision about existing backups. When that happens, return to analysis, ask for clarification, and then update the requirements.
Problem statement: Back up important files.
Important decisions are unspecified.
Functional requirements: 1. Accept a folder path as input. 2. Back up all files in that folder. 3. Save the backup in backups_YYYY-MM-DD in the user's home directory. 4. Clarify how existing backups and multiple versions are handled.
Required behaviors are recorded, and one remaining decision is explicitly marked for clarification.
Treat an unresolved question as part of the specification work. Recording the uncertainty is safer than hiding it in an assumption that later changes the program.
Different Interpretations
Two people can begin with the same vague request and produce different analyses because the request leaves decisions open. One person may interpret important files as every file in a selected folder, while another may expect only certain file types. They may also propose different destinations or different rules for existing backups. These differences are not evidence that analysis is unnecessary. They show why assumptions and decisions should be written down and reviewed.
Mistakes to Avoid
Common mistake Starting to code from a vague request
What it looks likeImplementing a backup program immediately after hearing that it should back up important files.
Why it failsThe files, destination, and backup version behavior have not been defined.
Do this insteadList the missing decisions and ask clarifying questions before designing the behavior.
Common mistake Treating an assumption as a requirement
What it looks likeSilently deciding that important files means every file in a folder.
Why it failsAnother person may expect a different selection rule.
Do this insteadRecord the assumption as a question or confirm it before placing it in the functional requirements.
Common mistake Believing analysis ends permanently before design
What it looks likeRefusing to revisit the analysis after a new design question appears.
Why it failsDesign can reveal gaps that were not obvious at first.
Do this insteadCycle back to analysis, obtain clarification, and update the requirements.
Common mistake Keeping the decisions only in conversation
What it looks likeRelying on memory instead of writing down the agreed program behavior.
Why it failsOther people cannot review an undocumented interpretation and misunderstandings may remain hidden.
Do this insteadWrite down the analysis and functional requirements for review.
Practice the Transition
A person asks for a program that organizes files. Before designing it, write four clarifying questions that would help determine the program's required behavior. Then convert the answers to those questions into a short functional requirements list.
Hints
- Ask what input the program receives.
- Ask what result the program should produce.
- Ask which rules determine how files are handled.
- Ask what should happen when an existing result or an unusual case is encountered.
Check your work by asking whether each requirement describes a program behavior and whether every important decision in the problem statement has an answer. If a question remains, the analysis is not finished.
Specification Checklist
- 1Analyze a problem statement before coding by locating missing details and ambiguities.
- 2Ask clarifying questions when the statement does not contain enough information to proceed.
- 3Use the answers from analysis to create a functional requirements list describing program behavior.
- 4Expect analysis and design to be iterative; return to analysis when design exposes a new gap.
- 5Write down decisions so other people can review the shared understanding before coding begins.
Key Takeaways
- Problem analysis finds the gaps and ambiguities that must be resolved before coding.
- Clarifying questions turn an incomplete problem statement into explicit decisions.
- Program design turns those decisions into a functional requirements list.
- Analysis and design can cycle back and forth when new questions appear.
- Writing down the specification helps people review and share the same understanding.