Writing maintainable programs

Maintainability describes how straightforward a program is for a programmer to understand, correct and change later. Code is often maintained by someone other than its original author, so its purpose and structure must be clear.

OCR requires four maintainability techniques:

• using subprograms to organise code into focused functions or procedures;
• following consistent, meaningful naming conventions;
• using indentation to show the structure of selection, iteration and subprograms;
• using comments appropriately to explain purpose or reasoning.

An examination question may show code and ask for improvements to that code. Suggest only changes that are genuinely needed. For example, do not recommend indentation if the supplied code is already indented clearly.

From working code to maintainable code

Both functions below can calculate an average, but the second is easier to understand and reuse.

def c(a):
    x = 0
    for y in a:
        x = x + y
    return x / len(a)

def calculate_average(scores):
    total_score = 0
    for score in scores:
        total_score = total_score + score
    return total_score / len(scores)

The improved names explain the role of each value. The subprogram has one clear purpose and can be tested separately. Indentation shows which statements belong to the loop and function.

A useful comment would explain a non-obvious decision, such as # Work from recorded scores only. A comment like # Add score to total immediately above total_score = total_score + score merely repeats obvious code.

Naming conventions and comments

A naming convention is a consistent set of rules for identifiers. Python commonly uses snake_case for variables and functions, such as ticket_total and calculate_price. OCR does not require one particular convention, but identifiers should be valid, consistent and meaningful.

Comments are written for programmers, not for the computer. They are useful when they explain:

• the purpose of a subprogram;
• why an unusual rule or calculation is required;
• an assumption that a future programmer must preserve.

Too many comments can make code harder to scan, especially when they repeat every obvious statement or are no longer updated when the code changes.

Practical task: write a focused function

Write a function called calculate_ticket_total(prices) that receives a list of ticket prices, calculates their total and returns it. Use meaningful identifiers and keep all statements correctly indented.

The function should work with different lists. Do not ask for input inside it, because the caller supplies the list through the parameter.

Review

Close your notes and state the four maintainability techniques required by OCR. For each one, give a precise example of a change you could make to code.

When a question supplies an algorithm, inspect it before answering. A contextual response such as “rename p to position” is stronger than the generic phrase “use meaningful variables”.