Creating a Program Specification
Problem analysis identifies gaps and ambiguities in a problem statement before you begin coding.
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.
Define the input: The program will accept a folder path as input.
Define the files: The program will back up all files in that folder.
Define the destination: The backup will be saved to a folder named backups_YYYY-MM-DD in the user's home directory.
Record 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.
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
Starting to code from a vague request
The files, destination, and backup version behavior have not been defined.
Fix:
List the missing decisions and ask clarifying questions before designing the behavior.Treating an assumption as a requirement
Another person may expect a different selection rule.
Fix:
Record the assumption as a question or confirm it before placing it in the functional requirements.Believing analysis ends permanently before design
Design can reveal gaps that were not obvious at first.
Fix:
Cycle back to analysis, obtain clarification, and update the requirements.Keeping the decisions only in conversation
Other people cannot review an undocumented interpretation and misunderstandings may remain hidden.
Fix:
Write 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
- Analyze a problem statement before coding by locating missing details and ambiguities.
- Ask clarifying questions when the statement does not contain enough information to proceed.
- Use the answers from analysis to create a functional requirements list describing program behavior.
- Expect analysis and design to be iterative; return to analysis when design exposes a new gap.
- Write 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.