Maintainable Code

Use subprograms, clear names, indentation and comments to make code easier to understand and change.

Maintainable code is easier to read, test, debug and modify. Structure and clarity matter as much as getting the correct output.

Predict

Read the code first. Do not run it yet.

maintainable-code-predict.py

def calc(p, q):
    r = p * q
    return r

print(calc(8, 5))

Predict before running

What does the code calculate?
Which names are vague?
Suggest clearer names without changing the behaviour.

Investigate

Use this code to explain exactly how the program works.

maintainable-code-investigate.py

def rectangle_area(length, width):
    # Calculate and return the area of a rectangle
    area = length * width
    return area

print(rectangle_area(8, 5))

Investigate the code

Which feature makes the code reusable?
How do the names improve readability?
What useful information does the comment add?

Four maintainability techniques

Technique	Purpose
Subprograms	split a larger problem into smaller reusable tasks
Naming conventions	make the role of variables and subprograms clear
Indentation	show program structure accurately
Comments	explain purpose or non-obvious decisions

maintainable.py

def calculate_average(total, count):
    # Return the mean of a known total and item count
    average = total / count
    return average

class_total = 420
student_count = 6
print(calculate_average(class_total, student_count))

Output

70.0

Comment purpose, not the obviousA useful comment explains why a section exists or what it is intended to do. Avoid comments that simply repeat a clear line of code.

Self-study guide

Maintainable code is easier for people to read, understand, test, fix and extend. OCR names four maintainability areas: use of subprograms, naming conventions, indentation and commenting.

Maintainability is not about making code longer. Good structure removes unnecessary repetition and makes the programmer’s intention clear. A useful comment explains purpose or reasoning rather than translating every obvious line into English.

OCR focusApply subprograms, naming conventions, indentation and appropriate commenting. Be able to explain why each improves maintainability.

OCR Exam Reference Language ↔ Python

OCR Exam Reference Language / term	Python	What to remember
`use of sub programs`	functions / procedure-style `def`	Break a larger problem into reusable, focused parts.
`naming conventions`	`meaningful snake_case names / UPPER_CASE constants`	Names communicate purpose.
`indentation`	`Python indentation is syntax`	Also visually shows program structure.
`commenting`	`# comment` in Python	Explain non-obvious purpose or logic.

Read both formsIn an examination you may see OCR Exam Reference Language even when you have learned the idea in Python. Translate the structure, not just the symbols.

Worked example

This program separates one calculation from the main program and names the fixed rule.

lesson-29-worked.py

PRICE_PER_STOP = 1.5

def calculate_fare(stops):
    fare = stops * PRICE_PER_STOP
    return fare

stops = int(input("Number of stops: "))
fare = calculate_fare(stops)

print("Fare:", fare)

Output

Fare: 7.5

Work through it line by line

PRICE_PER_STOP gives a meaningful name to a fixed value.
calculate_fare describes what the function does.
The function has one clear responsibility.
If the fare rule changes, the relevant logic is easy to locate.

Another example

Refactoring can replace repeated code with a reusable subprogram.

lesson-29-example-2.py

def show_result(player, score):
    print("Player:", player)
    print("Score:", score)

show_result("Nova", 18)
show_result("Ari", 22)

Output

Player: Nova
Score: 18
Player: Ari
Score: 22

Why this example matters

The presentation format is written once.
Every call uses the same structure, reducing duplicated code.

Common mistakes

Avoid these errors

Using single-letter names such as x and y when the meaning matters.
Commenting every obvious statement instead of useful reasoning.
Copy-pasting the same block repeatedly instead of creating a subprogram.
Inconsistent indentation that hides or breaks structure.

Exam-safe warningA comment should add information. # add 1 to count above count = count + 1 usually adds little value; explain the purpose instead.

Exam-ready checklist

You should now be able to

Identify features that improve maintainability.
Refactor repeated code into subprograms.
Use meaningful names and consistent conventions.
Apply indentation correctly.
Write useful, purposeful comments.

What you have learned

Use subprograms to structure code.
Choose meaningful names consistently.
Use correct indentation.
Use comments where they add useful explanation.