Maintainability: Use of sub programs; Naming conventions; Indentation; Commenting

Knowledge organiser

Defensive Design

2.3.1c

Understand why each of the identified maintainability techniques are useful and apply this appropriately

What you need to know

Maintainability refers to how easy it is to understand, update, and fix a program after it has been written. Good maintainability practices include using sub-programs to break code into manageable sections, following clear naming conventions for variables and functions, using proper indentation, and adding comments to explain the code.

Key points

Meaningful variable names: use descriptive names that explain what they STORE, e.g. totalPrice not tp, position not p.
Comments/annotation: explain what code does and why, making it easier for other programmers to follow/understand/debug.
Sub-programs (functions/procedures): put repeated code into reusable blocks. Note: 'Use a subroutine' alone is NOT enough — say the code will be PUT INTO a subroutine.
Using constants: store fixed values (e.g. PI = 3.142, MAX_POSITION = 512) so they can be 'updated once and it updates throughout'.
Indentation: visually shows the structure of code. NOTE: if the code is already indented, do NOT suggest indentation as an improvement.
Well-maintained code is easier to debug, update, and extend with new features.
Exam Tip:The question often says 'improve the maintainability of THIS algorithm'. You MUST refer to the specific code given, not give generic answers. Suggest specific variable renames, specific comments, etc.
Common Mistake:Don't say variables 'do' things — variables STORE/HOLD data. 'Describes what they store' is correct; 'describes what variables do' is not accepted.
Exam Tip:Replacing repeated code with a loop also improves maintainability (e.g. 5 separate array access lines → one FOR loop).
Exam Tip:A constant can be 'updated once and it updates throughout' the program — this is a key reason to use them.

Code examples

Good vs poor maintainability

python

# POOR maintainability
x = float(input("Enter value: "))
y = float(input("Enter value: "))
z = x / y
print(z)

# GOOD maintainability
# Calculate speed from distance and time
distance = float(input("Enter distance (m): "))
time = float(input("Enter time (s): "))
speed = distance / time  # speed = distance / time
print("Speed: " + str(speed) + " m/s")

# POOR maintainability x = float(input("Enter value: ")) y = float(input("Enter value: ")) z = x / y print(z) # GOOD maintainability # Calculate speed from distance and time distance = float(input("Enter distance (m): ")) time = float(input("Enter time (s): ")) speed = distance / time # speed = distance / time print("Speed: " + str(speed) + " m/s")