Documenting the Design of the Solution and Testing the Design

Welcome to Documenting and Testing the Design!

Hello and welcome to one of the most practical and rewarding areas of Software Systems Development! Before a builder lays a single brick for a house, they need detailed architectural blueprints. Writing software works in the exact same way. Before writing lines of code in C# or SQL, software engineers create detailed design documents and thoroughly test their ideas on paper.

In this chapter, you will learn how to clearly document your system design (from databases and class structures to user interfaces) and how to test those designs before programming begins. Don't worry if this seems like a lot of paperwork at first; we will break down every single concept into small, easy-to-digest steps!

1. Why Document the Design?

Documenting a design means recording exactly how your software will look, behave, and store data. It bridges the gap between what the client wants (the requirements) and what the programmer builds (the code).

Key reasons for documenting the design:
• Clear Communication: Ensures developers, project managers, and clients all share the same vision.
• Easier Maintenance: If a developer leaves the company, a new programmer can read the design docs and understand the system quickly.
• Error Reduction: Catching logical mistakes on paper is far cheaper and faster than rewriting thousands of lines of broken code later.
• Accurate Time and Cost Estimates: Clear designs allow teams to predict how long implementation will take.

Did you know? Finding and fixing a software bug during the design stage can cost up to \(100 \times\) less than fixing it after the software is released to users!

2. Documenting Data Structures and Databases

Software applications rely heavily on data. In the CCEA specification, you need to know how to document both persistent storage (databases) and in-memory data structures.

A. Data Dictionaries

A data dictionary is a structured reference file that defines all the metadata (data about data) for every field in your database tables. It ensures consistency across the whole system.

A comprehensive data dictionary entry includes:
• Field Name: A clear, standardised identifier (e.g., StudentID, DateOfBirth).
• Data Type: The type of data stored (e.g., VARCHAR(30), INT, DATETIME, BOOLEAN).
• Field Size / Length: Maximum characters or byte storage allowed (e.g., 50 characters).
• Key Type: Primary Key (PK), Foreign Key (FK), or non-key.
• Validation Rules: Rules to ensure data integrity (e.g., Range check: Age \(\ge 18\), Format check, Presence check / NOT NULL).
• Description: A simple explanation of what the field stores.

B. Entity Relationship Diagrams (ERDs)

An ERD is a visual diagram showing the entities (tables) in a system and how they connect to one another through relationships.

• One-to-One (\(1:1\)): E.g., One citizen has one passport.
• One-to-Many (\(1:M\)): E.g., One customer places many orders.
• Many-to-Many (\(M:N\)): E.g., Many students enrol in many modules. (Remember: in relational design, \(M:N\) relationships must be resolved into two \(1:M\) relationships using a junction/link entity!).

Key Takeaway for Data Documentation

Quick Review: The ERD shows the "big picture" of how entities relate, while the Data Dictionary provides the deep-dive technical rules and attributes for every single field.

3. Documenting Object-Oriented Architecture and Logic

Because C# is an Object-Oriented Programming (OOP) language, you must document classes, objects, and algorithmic workflows using standard modelling techniques like UML (Unified Modelling Language).

A. UML Class Diagrams

A UML Class Diagram gives a static blueprint of the classes that will exist in the software.

Each class box is split into three horizontal sections:
1. Top Section: Class Name (e.g., BankAccount).
2. Middle Section: Attributes / Fields (e.g., - balance: double).
3. Bottom Section: Methods / Operations (e.g., + Deposit(amount: double): void).

Visibility Modifiers

Visibility controls how accessible an attribute or method is (supporting the OOP concept of encapsulation):
• \(+\) (Public): Accessible from any other class.
• \(-\) (Private): Accessible only within the declaring class.
• \(\#\) (Protected): Accessible within the class and any child/derived classes.

Class Relationships to Remember

• Inheritance / Generalisation: An "is-a" relationship (e.g., Car is a Vehicle). Represented by a line with an open triangle pointing to the parent/base class.
• Association: A general "uses-a" relationship between two independent classes.
• Aggregation: A "has-a" relationship where the child can exist independently of the parent (e.g., Department has Teachers; if the department closes, teachers still exist). Represented by a hollow diamond.
• Composition: A strong "part-of" relationship where child objects cannot exist without the parent (e.g., Building has Rooms; destroy the building, and the rooms cease to exist). Represented by a filled solid diamond.

B. Sequence Diagrams

While class diagrams show the static structure, Sequence Diagrams show dynamic interaction. They display how objects collaborate step-by-step over time to complete a specific task (e.g., logging in or processing a card payment).

Key visual elements in sequence diagrams:
• Lifeline: Vertical dashed lines representing the existence of an object over time.
• Activation Bar: Narrow vertical rectangles on a lifeline showing when an object is actively executing code.
• Messages: Horizontal solid arrows showing method calls, with dashed arrows showing return values.

C. Logic Tools: Pseudocode and Flowcharts

For complex business logic or algorithmic functions, developers use pseudocode or flowcharts before writing code.
• Pseudocode: Structured, human-readable language resembling code without strict syntax rules. It focuses purely on algorithm logic.
• Flowcharts: Visual diagrams using standard symbols (terminators, decision diamonds, process rectangles, input/output parallelograms) to display decision paths and loops.

4. Documenting the User Interface (UI)

A functional backend is useless if users cannot navigate the frontend. Documenting user interfaces ensures high usability and accessibility.

Common UI Documentation Tools:
• Wireframes: Low-fidelity structural sketches showing the basic layout of controls (textboxes, labels, buttons, grids) on a screen.
• Mock-ups / Prototypes: High-fidelity, detailed visual previews including exact colours, fonts, brand logos, and spacing.
• Storyboards / Navigation Maps: Flow diagrams illustrating how users move from screen to screen when clicking buttons or selecting menu items.

HCI (Human-Computer Interaction) Principles to Document:
• Consistency in layout and colour palettes.
• Clear error messaging and validation feedback.
• Keyboard shortcuts and tab order accessibility for non-mouse users.

5. Testing and Verifying the Design

Testing does not begin when coding is finished; it begins in the design phase! Validating designs early prevents developers from building the wrong solution or implementing flawed algorithms.

A. Design Walkthroughs and Peer Reviews

A design walkthrough is a formal meeting where the designer presents the diagrams, data dictionaries, and pseudocode to team members (developers, testers, and system analysts). The team steps through common scenarios to spot missing fields, logic flaws, or inefficient structures.

B. Desk Checking and Trace Tables

Desk checking is a manual, non-computerised technique where you sit with pencil and paper and step through an algorithm line-by-line using sample inputs.

You record the state of every variable after each step inside a trace table.

Trace Table Walkthrough Example

Consider this simple pseudocode algorithm designed to calculate the sum of even numbers up to 6:

1: total = 0
2: count = 2
3: WHILE count \(\le\) 6 DO
4:     total = total + count
5:     count = count + 2
6: END WHILE

Let's trace this step-by-step:

• Initial State: Line 1 sets \(total = 0\). Line 2 sets \(count = 2\).
• Iteration 1: Condition (\(2 \le 6\)) is True. Total becomes \(0 + 2 = 2\). Count becomes \(2 + 2 = 4\).
• Iteration 2: Condition (\(4 \le 6\)) is True. Total becomes \(2 + 4 = 6\). Count becomes \(4 + 2 = 6\).
• Iteration 3: Condition (\(6 \le 6\)) is True. Total becomes \(6 + 6 = 12\). Count becomes \(6 + 2 = 8\).
• Termination: Condition (\(8 \le 6\)) is False. Loop exits. Final Total = \(12\).

Desk checking confirms the logic works correctly before writing a single line of C#!

6. Creating a Comprehensive Test Plan

A Test Plan is a formal document prepared during the design stage that outlines exactly how the final software will be verified. It defines all test scenarios, expected outputs, and the specific test data to be used.

Structure of a Test Case

A standard test case table includes:
• Test ID: A unique code (e.g., TC01, TC02).
• Test Description: What is being tested (e.g., Verify user cannot enter an age under 18).
• Test Data: The exact input values provided to the system.
• Test Type: Normal, Boundary / Extreme, or Erroneous / Invalid.
• Expected Result: What the system should do if it works perfectly.
• Actual Result: Filled out later during the implementation/testing stage.
• Pass / Fail: Recorded after running the test.

Categories of Test Data

To ensure total test coverage, every input field must be tested with three distinct types of data:

1. Normal Data: Data that is valid and falls comfortably within the expected range.
Example: If a field accepts exam marks between \(0\) and \(100\), normal data could be \(45\) or \(78\).

2. Boundary / Extreme Data: Data that lies right on the edge of the acceptable limits.
Example: For marks between \(0\) and \(100\), boundary values are exactly \(0\) and \(100\), as well as adjacent values like \(1\) and \(99\).

3. Erroneous / Invalid Data: Data that is completely unacceptable or of the wrong format and should trigger an error message.
Example: Entering \(-5\), \(105\), or the word "Seventy" into the numerical mark field.

Memory Mnemonic for Test Data:
Remember the acronym N-B-E: Never Build Errors! (Normal, Boundary, Erroneous).

7. Common Mistakes to Avoid in Exams and Coursework

• Mixing up Boundary and Erroneous data: Boundary data is valid data on the extreme limit (e.g., \(18\) for an \(\ge 18\) rule). Erroneous data is invalid (e.g., \(17\) or \(-1\)).
• Vague Expected Results: Never write "It should give an error" in a test plan. Always write the exact expected outcome: "Display error dialog: 'Age must be 18 or older' and prevent form submission."
• Ignoring Visibility in UML: Don't forget \(+\), \(-\), and \(\#\) symbols on your class diagrams.
• Skipping Trace Table Steps: In trace tables, only update a variable's value on the line where it actually changes. Do not re-write untouched values on every single row unless required by the specific question format.

8. Chapter Summary and Key Takeaways

• Design Documentation acts as the complete blueprint for software, covering data storage (data dictionaries, ERDs), system architecture (UML class and sequence diagrams), and user interaction (wireframes).
• Pre-Implementation Testing involves walkthroughs, peer reviews, and desk checking (trace tables) to eliminate logic bugs before coding starts.
• Test Plans must be designed in advance, incorporating Normal, Boundary, and Erroneous data to test every scenario thoroughly.