Planning for Maintainability

This lesson covers how to write maintainable programs as required by OCR J277 Section 2.4. Maintainability means writing code that other programmers (or your future self) can easily read, understand, and modify. Good maintainability practices are essential for professional programming and are frequently tested in the OCR exam.

---

What Is Maintainability?

A maintainable program is one that can be easily:

• Read and understood by another programmer
• Modified to fix bugs or add new features
• Extended to handle new requirements
• Debugged when problems arise

Programs rarely remain unchanged after they are first written. They need to be updated, fixed, and improved over time — often by programmers who did not write the original code. Making code maintainable saves time and reduces errors.

---

Key Maintainability Techniques

1. Comments

Comments are notes within the code that explain what the code does and why. They are ignored by the computer but are invaluable for human readers.

OCR Pseudocode:

// Calculate the final price including VAT
const VAT_RATE = 0.20
price = real(input("Enter price: "))
total = price + (price * VAT_RATE)  // Add 20% VAT
print("Total: £" + str(total))

Python:

# Calculate the final price including VAT
VAT_RATE = 0.20
price = float(input("Enter price: "))
total = price + (price * VAT_RATE)  # Add 20% VAT
print(f"Total: £{total:.2f}")

Good Commenting Practices

Do	Don't
Explain why the code does something	State the obvious (e.g. x = 5 // set x to 5)
Describe the purpose of functions	Comment every single line
Note any assumptions or limitations	Write comments longer than the code itself
Keep comments up to date	Leave outdated comments that no longer match the code

OCR Exam Tip: When asked "how would you make this program more maintainable?", commenting is usually worth 1 mark. But be specific — say "add comments to explain the purpose of each function" rather than just "add comments."

---

2. Meaningful Identifier Names

Identifiers are the names given to variables, constants, functions, and procedures. Using meaningful names makes code self-documenting.

Poor Name	Good Name	Why Better
x	totalScore	Clearly describes what the variable stores
a	studentAge	Immediately understandable
fn	calculateAverage	Describes what the function does
temp	temperatureCelsius	Specific and unambiguous
lst	studentNames	Describes the contents of the list

Naming Conventions

Convention	Example	Usage
camelCase	totalScore, firstName	Variables and functions
UPPER_CASE	VAT_RATE, MAX_SIZE	Constants
snake_case	total_score, first_name	Python convention for variables

---

3. Indentation

Indentation (using spaces or tabs to offset code blocks) shows the structure of the program, making it clear which code belongs to which block (loops, if statements, functions).

Well-indented code:

for i = 0 to 9
    if scores[i] > highestScore then
        highestScore = scores[i]
        bestStudent = names[i]
    endif
next i

Poorly indented code (same logic but hard to read):

for i = 0 to 9
if scores[i] > highestScore then
highestScore = scores[i]
bestStudent = names[i]
endif
next i

OCR Exam Tip: In Python, indentation is not just good practice — it is required syntax. Incorrect indentation in Python causes errors. In pseudocode exams, always indent code inside loops, if statements, and subroutines to show clear structure.

---

4. Use of Subroutines (Sub-Programs)

Breaking code into subroutines (functions and procedures) makes it more maintainable because:

• Each subroutine has a single, clear purpose
• Subroutines can be tested independently
• Changes to one subroutine do not affect others
• Code is reused rather than duplicated

Before (one long block of code):

// All code in one block — hard to maintain
// ... 200 lines of mixed input, processing, output ...

After (structured with subroutines):

procedure getInput()
    // handles all user input
endprocedure

function calculateResult(data)
    // processes the data and returns result
endfunction

procedure displayOutput(result)
    // displays the result to the user
endprocedure

// Main program — clear and readable
getInput()
result = calculateResult(data)
displayOutput(result)

---

Worked Example: Refactoring for Maintainability

Before (poor maintainability):

a = int(input(""))
b = int(input(""))
c = int(input(""))
d = (a + b + c) / 3
if d >= 50 then
print("P")
else
print("F")
endif

After (good maintainability):

// Program to calculate average mark and determine pass/fail
const PASS_MARK = 50
const NUM_SUBJECTS = 3

function getMarks()
    total = 0
    for i = 1 to NUM_SUBJECTS
        mark = int(input("Enter mark for subject " + str(i) + ": "))
        total = total + mark
    next i
    return total
endfunction

function calculateAverage(total, count)
    return total / count
endfunction

procedure displayResult(average)
    if average >= PASS_MARK then
        print("Pass — average: " + str(average))
    else
        print("Fail — average: " + str(average))
    endif
endprocedure

// Main program
totalMarks = getMarks()
averageMark = calculateAverage(totalMarks, NUM_SUBJECTS)
displayResult(averageMark)

---

Summary of Maintainability Techniques

Technique	Benefit
Comments	Explain the purpose and logic of code
Meaningful names	Make code self-documenting and readable
Indentation	Shows the structure of code blocks
Subroutines	Break code into manageable, testable units
Constants	Make values easy to update and prevent magic numbers

flowchart LR
    subgraph Before [Before — unmaintainable]
        B1[a, b, c, d single letters]
        B2[Magic numbers 50, 3]
        B3[No comments / no indent]
        B4[All logic in one block]
    end
    subgraph After [After — maintainable]
        A1[score1, score2, score3, average]
        A2[Constants PASS_MARK, NUM_SUBJECTS]
        A3[Header + inline comments, indented]
        A4[Subroutines: getMarks / calculateAverage / displayResult]
    end
    Before -- Refactor --> After

---

Summary

• Maintainability means code can be easily read, understood, and modified.
• Use comments to explain why (not what) the code does.
• Use meaningful identifier names that describe the purpose of variables and functions.
• Use consistent indentation to show code structure.
• Use subroutines to break the program into logical, reusable components.
• Use constants instead of "magic numbers" scattered through code.