Defining Requirements Clearly
Problem analysis identifies gaps and ambiguities in a problem statement before you begin coding.
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.
- Read the request and identify what the program is supposed to accomplish.
- Look for missing details or ambiguous words that could support more than one interpretation.
- Ask questions about the decisions the program must make.
- Record the answers, along with any rules or limitations that affect the behavior.
- Decide whether enough information exists to begin design.
Analyzing the backup request
Someone asks for a program that backs up important files.
Identify 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.
Identify the destination decision: The request does not say where the backup belongs. Ask for the required destination.
Identify the existing-backup rule: The request does not say whether an existing backup should be overwritten or whether multiple versions should be kept.
Check 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.
Specify the input: The program will accept a folder path as input.
Specify the files: The program will back up all files in that folder.
Specify the destination: The backup will be saved to a folder named backups_YYYY-MM-DD in the user's home directory.
Record 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.
- Write each important behavior as a separate requirement.
- Use the answers discovered during analysis rather than the original vague wording.
- Include decisions about inputs, outputs, selections, destinations, and rules when they affect behavior.
- Review 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 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.
Starting to code from a vague request
The request does not define which files are important, where the backup belongs, or how existing backups should be handled.
Fix:
List the missing decisions and ask clarifying questions before designing the program.Treating the analysis as the solution
Analysis is for understanding the problem. Design must convert the answers into a functional requirements list.
Fix:
After the important questions are answered, write the concrete actions the program must perform.Assuming the first design is final
Analysis and design are iterative, so design can reveal new gaps.
Fix:
Cycle back to analysis, resolve the new question, and update the requirements.Keeping requirements only in one person's head
Other people cannot review an unwritten interpretation and catch misunderstandings.
Fix:
Write 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
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
- Problem analysis identifies gaps and ambiguities before coding begins.
- Clarifying questions reveal the decisions and rules that the program must follow.
- Program design turns the answers from analysis into a functional requirements list.
- If design reveals a new gap, return to analysis instead of guessing.
- Written analysis and requirements create a shared understanding that others can review.
Key Takeaways
- 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.