Defining Requirements Clearly
Write the analysis and requirements down so other people can review the decisions, identify misunderstandings, and agree on the intended behavior.
The Stopping Point
A programming task can sound simple and still be impossible to begin responsibly. Consider the request: write a program that backs up important files. The action seems obvious: copy files from one place to another. However, the request does not say which files count as important, where the backup should go, or what should happen when a backup already exists. Before writing code, you need to discover what the program is actually required to do.
Reading the Gaps
Problem analysis is the understanding phase that comes before coding. Its purpose is not to solve the problem yet. Its purpose is to identify what you need to know, which decisions must be made, and which rules the program must follow.
- 1Read the request and identify what the program is supposed to accomplish.
- 2Look for missing details or ambiguous words that could support more than one interpretation.
- 3Ask questions about the decisions the program must make.
- 4Record the answers, along with any rules or limitations that affect the behavior.
- 5Decide whether enough information exists to begin design.
Analyzing the backup request
Someone asks for a program that backs up important files.
- 1Identify the missing selection rule
The word important does not specify which files to copy. Ask whether the program should copy all files, selected types, or files chosen in another way.
- 2Identify the destination decision
The request does not say where the backup belongs. Ask for the required destination.
- 3Identify the existing-backup rule
The request does not say whether an existing backup should be overwritten or whether multiple versions should be kept.
- 4Check readiness
If these answers are not available, the problem is not sufficiently understood for design. More clarification is needed.
The analysis has exposed the decisions that must be answered before a concrete program behavior can be specified.
Sorting the Information
A useful analysis separates different kinds of information that appear in a problem discussion. Some details describe what the program must do. Other details limit how that behavior can occur. Still others are assumptions that have not yet been confirmed. The source material emphasizes asking what must be known, which decisions must be made, and what rules the program must follow; organizing the answers this way makes those questions easier to review.
| Information to examine | Question it raises | Effect on design |
|---|---|---|
| Required behavior | What action must the program perform? | Becomes part of the functional requirements. |
| Constraints | What rules must the program follow? | Limits the possible behavior. |
| Assumptions | Which interpretation has not been confirmed? | Requires clarification before relying on it. |
An analysis checklist for organizing unanswered details.
Building the Requirements List
Program design begins after analysis has answered enough of the open questions. Design turns those answers into a concrete list of how the program should behave. This list is the functional requirements specification that guides coding.
A design for the backup program
Turn the clarified backup decisions into functional requirements.
- 1Specify the input
The program will accept a folder path as input.
- 2Specify the files
The program will back up all files in that folder.
- 3Specify the destination
The backup will be saved to a folder named backups_YYYY-MM-DD in the user's home directory.
- 4Record the behavior
These statements describe concrete program behavior rather than leaving the earlier questions unresolved.
The functional requirements now provide a design direction for coding: accept a folder path, select the files in that folder, and save the backup in the specified dated folder.
- 1Write each important behavior as a separate requirement.
- 2Use the answers discovered during analysis rather than the original vague wording.
- 3Include decisions about inputs, outputs, selections, destinations, and rules when they affect behavior.
- 4Review the list to see whether another unanswered question prevents a clear design.
Designs That Diverge
| Analyst A | Analyst B |
|---|---|
| Interprets the backup request as applying to all files in a supplied folder. | Interprets the backup request as requiring a way to select only certain files. |
| Designs a dated backup folder in the user's home directory. | Seeks a destination choice before specifying storage behavior. |
| Produces requirements after assuming the clarified choices. | Keeps additional questions open until the choices are confirmed. |
Different interpretations of an incomplete request can lead to different analysis and design paths.
Different people may analyze and design the same problem differently because an incomplete problem statement leaves room for interpretation. The practical response is not to assume that one person's first design is automatically correct. Write the analysis and requirements down so other people can review the decisions, identify misunderstandings, and agree on the intended behavior.
Reviewing the Work
Before coding, ask whether every important decision has an answer. If the program's inputs, actions, destinations, or rules are still unclear, continue analysis. If the answers are clear, record them as functional requirements and use that list as the design guide.
Common mistake Starting to code from a vague request
What it looks likeBeginning a backup program immediately after hearing the phrase back up important files.
Why it failsThe request does not define which files are important, where the backup belongs, or how existing backups should be handled.
Do this insteadList the missing decisions and ask clarifying questions before designing the program.
Common mistake Treating the analysis as the solution
What it looks likeSpending time listing unanswered questions but never turning the answers into program behavior.
Why it failsAnalysis is for understanding the problem. Design must convert the answers into a functional requirements list.
Do this insteadAfter the important questions are answered, write the concrete actions the program must perform.
Common mistake Assuming the first design is final
What it looks likeRefusing to revisit the requirements when a design decision exposes another unanswered question.
Why it failsAnalysis and design are iterative, so design can reveal new gaps.
Do this insteadCycle back to analysis, resolve the new question, and update the requirements.
Common mistake Keeping requirements only in one person's head
What it looks likeRelying on an informal interpretation of what the requester meant.
Why it failsOther people cannot review an unwritten interpretation and catch misunderstandings.
Do this insteadWrite down the analysis and design so they can be reviewed before coding begins.
Practice Check
A person asks you to write a program that organizes their files. Before coding, identify three clarifying questions you would ask. Then describe how the answers would become functional requirements.
Hints
- Ask what files should be included.
- Ask what organization or destination the program should use.
- Ask what rules the program should follow when files already exist or do not fit the chosen categories.
What do you think happens?
You have written a first design, but one of its decisions raises a new unanswered question. What should you do next?
Reveal answer
Return to analysis and seek clarification
Analysis and design are iterative. A new gap discovered during design is a reason to cycle back to analysis, not a reason to guess.
Key Takeaways
- 1Problem analysis identifies gaps and ambiguities before coding begins.
- 2Clarifying questions reveal the decisions and rules that the program must follow.
- 3Program design turns the answers from analysis into a functional requirements list.
- 4If design reveals a new gap, return to analysis instead of guessing.
- 5Written analysis and requirements create a shared understanding that others can review.
At a glance
- A simple-sounding programming request may lack the information needed to begin responsibly.
- Problem analysis asks what must be known, which decisions must be made, and what rules must be followed.
- Functional requirements record the concrete behavior established during design.
- Analysis and design can loop back and forth when new questions appear.
- Different interpretations are possible when a problem statement is incomplete, so written requirements should be reviewed.