Use of sub programs; Naming conventions; Indentation; Commenting

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

2.3.1 Defensive Design

Defensive Design — Note 3 of 3

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.

What to know

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.
In Python a comment starts with #. In OCR Exam Reference Language comments start with //. Comments are ignored when the program runs.

Exam technique

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.
Mistake:Don't say variables 'do' things — variables STORE/HOLD data. 'Describes what they store' is correct; 'describes what variables do' is not accepted.
Tip:Replacing repeated code with a loop also improves maintainability (e.g. 5 separate array access lines → one FOR loop).
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")

Comments in Python

python

# This is a comment: Python ignores it when the program runs.
# Use comments to explain WHAT a section does and WHY.

total = 0   # running total of all the scores (an inline comment)

Ready to test yourself?

Practise 2.3.1 questions

← Previous noteInput validation2.3.1 Defensive Design Next topic →Testing2.3.2 Testing

Back to Defensive Design

Revise another OCR GCSE topic: Testing

# 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")