Techniques for readable, maintainable code

What you'll learn

How layout means arranging code so its structure is clear.
How indentation means spaces at the start of lines, especially to show blocks in Python.
How comments are notes ignored by Python but useful to human readers.
How meaningful identifiers and white space help make programs easier to read, understand and maintain — that means fix, improve or extend later.

The aim: code that humans can understand

A program is not only written for the computer. It is also read by people: your teacher, an examiner, another programmer, and future you.

Definition

Source code

Source code is the human-written set of instructions, such as Python 3 code, that a programmer writes before the program is run.

Definition

Readable and maintainable code

Readable code is source code that a person can follow without unnecessary effort. Maintainable code is code that can be corrected, improved or extended later without causing avoidable new errors.

A program can work correctly but still be difficult to maintain. If the names are unclear, the indentation is messy, or everything is crammed onto one line, it becomes harder to spot mistakes or make changes safely.

Key Idea

The main aim

Readable, maintainable code makes the program’s purpose and structure clear to a human reader without changing what the program does.

Layout and white space

Layout: arranging the program clearly

Definition

Layout

Layout is the overall arrangement of code on the page, including the order of lines, line breaks, and grouping of related instructions.

Good layout usually means:

putting input, processing and output in a sensible order
using one main instruction per line
grouping related lines together
avoiding very long lines that are hard to scan

White space: useful empty space

Definition

White space

White space means characters that create space, such as spaces, blank lines and tabs. In readable code, white space is used to separate ideas and make expressions easier to read.

An operator is a symbol or word that performs an action, such as +, *, >= or and. In Python, spaces around operators often make expressions easier to read:

total_cost = adult_tickets * 12 + child_tickets * 7

Blank lines can also separate stages of a program, such as input, calculation and output.

Example

Improving layout and white space

This program works, but it is difficult to read because everything is squeezed together:

a=int(input("Adults: "));c=int(input("Children: "));t=a*12+c*7;print("Total: £",t)

Separate the program into three jobs: get the inputs, calculate the total cost, and display the output.
Put each job on its own line or group of lines, so the reader can scan the program in order.
Add spaces around operators and after commas, without changing the calculation:

adult_tickets = int(input("Adults: "))
child_tickets = int(input("Children: "))

total_cost = adult_tickets * 12 + child_tickets * 7

print("Total: £", total_cost)

Common Mistake

Cramming code onto one line

Python allows some statements to be put on the same line, but GCSE code should normally be written one clear step per line. A short program is not automatically a readable program.

Indentation

Definition

Indentation

Indentation is the white space at the start of a line. In Python, indentation is used to show which lines belong inside a block of code.

Definition

Code block

A code block is a group of statements that belong together, such as the statements controlled by an if, else, for or while line.

In Python, indentation is not just decoration. It affects how the program runs. A block often begins after a line ending with a colon :.

For example:

if mark >= 50:
    print("Pass")
else:
    print("Fail")

The two print lines are indented because each one belongs inside a branch of the if statement.

Example

Fixing indentation in a loop

This code is meant to add three numbers, but the indentation is wrong:

total = 0
for count in range(3):
number = int(input("Number: "))
total = total + number
print(total)

The colon after for count in range(3): starts a repeated block, so the input and addition lines must be indented inside that block.
The final print(total) should run once after all three numbers have been added, so it should stay outside the repeated block.
Apply the same indentation to all lines that should repeat:

total = 0

for count in range(3):
    number = int(input("Number: "))
    total = total + number

print(total)

Common Mistake

Indentation can change the result

Moving a line one indentation level can change how many times it runs. For example, printing inside a loop displays a running total, while printing after the loop displays only the final total.

Comments

Definition

Comment

A comment is a note in the source code for human readers. In Python, a comment starts with #, and Python ignores everything after it on that line.

Comments are useful when they explain:

the purpose of a section of code
an assumption or rule being used
a decision that is not obvious from the code alone

They are less useful when they simply repeat what the code already says.

# Add 1 to count
count = count + 1

That comment does not help much because the code is already clear.

Example

Replacing noisy comments

This code has comments, but they mostly repeat the Python:

# set t to 0
t = 0
# loop through marks
for m in marks:
    # add m to t
    t = t + m

Remove comments that only translate the code into English, because they add clutter rather than understanding.
Notice that the unclear names t and m are making the comments do too much work.
Use clearer names, then keep one useful comment that explains the purpose of the calculation:

# Calculate the total mark so the mean can be found later.
total_mark = 0
for mark in marks:
    total_mark = total_mark + mark

Tip

Comment the why

A helpful comment often explains why something is being done. If a comment only explains what a line does, the code may need clearer identifiers instead.

Meaningful identifiers

Definition

Identifier

An identifier is a name chosen by the programmer for something in a program, such as a variable. A variable is a named storage location for a value that can change while the program runs.

A meaningful identifier describes the role of the value in the program.

Weak names:

a
x
data1
thing

Clearer names:

adult_tickets
total_cost
student_name
is_valid

In Python, identifiers:

can contain letters, digits and underscores
cannot start with a digit
cannot contain spaces
cannot be Python keywords such as if, for or while
are case-sensitive, so score and Score are different names

Many Python programmers use snake_case, which means lowercase words separated by underscores, such as total_cost.

Example

Choosing identifiers for a password check

This code checks whether a password is at least 8 characters long, but the names are unclear:

x = input("Password: ")
y = len(x)
z = y >= 8

Work out what each stored value represents: the password itself, its length, and whether it is long enough.
Choose names that describe those roles, not just short labels.
Replace the identifiers consistently while keeping the same logic:

password = input("Password: ")
password_length = len(password)
is_long_enough = password_length >= 8

Common Mistake

Only naming the data type

Names like number1, string2 or list_value are often too vague. A good identifier explains the value’s purpose, such as ticket_count, customer_name or test_scores.

Putting the techniques together

When you improve code without changing what it does, you are refactoring it. For GCSE, you do not need a deep theory of refactoring, but you should be able to make practical readability improvements.

A sensible order is:

Fix indentation first, because in Python it can affect correctness.
Rename unclear identifiers so the purpose of values is visible.
Improve layout by separating input, processing and output.
Add white space around operators and blank lines between logical sections.
Add comments only where they genuinely help explain purpose or decisions.

Key Idea

Readable does not mean different

Unless the question asks you to change the program’s behaviour, readability improvements should keep the same inputs, processing and outputs.

Exam technique

In the exam

If asked to make code easier to read or maintain, make actual changes: indent blocks, split long lines, rename unclear identifiers, add useful comments and use white space.
Do not just write “add comments” as a vague answer; show or describe a helpful comment that explains purpose.
Link your answer to human benefits: easier to understand, easier to find mistakes, and easier to change later.

Self review

Check yourself

What is the difference between indentation and ordinary white space in Python?
Why is total_cost a better identifier than x in a ticket-price program?
When might a comment make code worse rather than better?

Techniques for readable, maintainable code

What you'll learn

How layout means arranging code so its structure is clear.
How indentation means spaces at the start of lines, especially to show blocks in Python.
How comments are notes ignored by Python but useful to human readers.
How meaningful identifiers and white space help make programs easier to read, understand and maintain — that means fix, improve or extend later.

The aim: code that humans can understand

A program is not only written for the computer. It is also read by people: your teacher, an examiner, another programmer, and future you.

Definition

Source code

Source code is the human-written set of instructions, such as Python 3 code, that a programmer writes before the program is run.

Definition

Readable and maintainable code

Key Idea

The main aim

Readable, maintainable code makes the program’s purpose and structure clear to a human reader without changing what the program does.

Layout and white space

Layout: arranging the program clearly

Definition

Layout

Layout is the overall arrangement of code on the page, including the order of lines, line breaks, and grouping of related instructions.

Good layout usually means:

putting input, processing and output in a sensible order
using one main instruction per line
grouping related lines together
avoiding very long lines that are hard to scan

White space: useful empty space

Definition

White space

White space means characters that create space, such as spaces, blank lines and tabs. In readable code, white space is used to separate ideas and make expressions easier to read.

An operator is a symbol or word that performs an action, such as +, *, >= or and. In Python, spaces around operators often make expressions easier to read:

total_cost = adult_tickets * 12 + child_tickets * 7

Blank lines can also separate stages of a program, such as input, calculation and output.

Example

Improving layout and white space

This program works, but it is difficult to read because everything is squeezed together:

a=int(input("Adults: "));c=int(input("Children: "));t=a*12+c*7;print("Total: £",t)

Separate the program into three jobs: get the inputs, calculate the total cost, and display the output.
Put each job on its own line or group of lines, so the reader can scan the program in order.
Add spaces around operators and after commas, without changing the calculation:

adult_tickets = int(input("Adults: "))
child_tickets = int(input("Children: "))

total_cost = adult_tickets * 12 + child_tickets * 7

print("Total: £", total_cost)

Common Mistake

Cramming code onto one line

Python allows some statements to be put on the same line, but GCSE code should normally be written one clear step per line. A short program is not automatically a readable program.

Indentation

Definition

Indentation

Indentation is the white space at the start of a line. In Python, indentation is used to show which lines belong inside a block of code.

Definition

Code block

A code block is a group of statements that belong together, such as the statements controlled by an if, else, for or while line.

In Python, indentation is not just decoration. It affects how the program runs. A block often begins after a line ending with a colon :.

For example:

if mark >= 50:
    print("Pass")
else:
    print("Fail")

The two print lines are indented because each one belongs inside a branch of the if statement.

Example

Fixing indentation in a loop

This code is meant to add three numbers, but the indentation is wrong:

total = 0
for count in range(3):
number = int(input("Number: "))
total = total + number
print(total)

The colon after for count in range(3): starts a repeated block, so the input and addition lines must be indented inside that block.
The final print(total) should run once after all three numbers have been added, so it should stay outside the repeated block.
Apply the same indentation to all lines that should repeat:

total = 0

for count in range(3):
    number = int(input("Number: "))
    total = total + number

print(total)

Common Mistake

Indentation can change the result

Moving a line one indentation level can change how many times it runs. For example, printing inside a loop displays a running total, while printing after the loop displays only the final total.

Comments

Definition

Comment

A comment is a note in the source code for human readers. In Python, a comment starts with #, and Python ignores everything after it on that line.

Comments are useful when they explain:

the purpose of a section of code
an assumption or rule being used
a decision that is not obvious from the code alone

They are less useful when they simply repeat what the code already says.

# Add 1 to count
count = count + 1

That comment does not help much because the code is already clear.

Example

Replacing noisy comments

This code has comments, but they mostly repeat the Python:

# set t to 0
t = 0
# loop through marks
for m in marks:
    # add m to t
    t = t + m

Remove comments that only translate the code into English, because they add clutter rather than understanding.
Notice that the unclear names t and m are making the comments do too much work.
Use clearer names, then keep one useful comment that explains the purpose of the calculation:

# Calculate the total mark so the mean can be found later.
total_mark = 0
for mark in marks:
    total_mark = total_mark + mark

Tip

Comment the why

A helpful comment often explains why something is being done. If a comment only explains what a line does, the code may need clearer identifiers instead.

Meaningful identifiers

Definition

Identifier

An identifier is a name chosen by the programmer for something in a program, such as a variable. A variable is a named storage location for a value that can change while the program runs.

A meaningful identifier describes the role of the value in the program.

Weak names:

a
x
data1
thing

Clearer names:

adult_tickets
total_cost
student_name
is_valid

In Python, identifiers:

can contain letters, digits and underscores
cannot start with a digit
cannot contain spaces
cannot be Python keywords such as if, for or while
are case-sensitive, so score and Score are different names

Many Python programmers use snake_case, which means lowercase words separated by underscores, such as total_cost.

Example

Choosing identifiers for a password check

This code checks whether a password is at least 8 characters long, but the names are unclear:

x = input("Password: ")
y = len(x)
z = y >= 8

Work out what each stored value represents: the password itself, its length, and whether it is long enough.
Choose names that describe those roles, not just short labels.
Replace the identifiers consistently while keeping the same logic:

password = input("Password: ")
password_length = len(password)
is_long_enough = password_length >= 8

Common Mistake

Only naming the data type

Names like number1, string2 or list_value are often too vague. A good identifier explains the value’s purpose, such as ticket_count, customer_name or test_scores.

Putting the techniques together

A sensible order is:

Fix indentation first, because in Python it can affect correctness.
Rename unclear identifiers so the purpose of values is visible.
Improve layout by separating input, processing and output.
Add white space around operators and blank lines between logical sections.
Add comments only where they genuinely help explain purpose or decisions.

Key Idea

Readable does not mean different

Unless the question asks you to change the program’s behaviour, readability improvements should keep the same inputs, processing and outputs.

Exam technique

In the exam

If asked to make code easier to read or maintain, make actual changes: indent blocks, split long lines, rename unclear identifiers, add useful comments and use white space.
Do not just write “add comments” as a vague answer; show or describe a helpful comment that explains purpose.
Link your answer to human benefits: easier to understand, easier to find mistakes, and easier to change later.

Self review

Check yourself

What is the difference between indentation and ordinary white space in Python?
Why is total_cost a better identifier than x in a ticket-price program?
When might a comment make code worse rather than better?

Techniques for readable, maintainable code

What you'll learn

The aim: code that humans can understand

Layout and white space

Layout: arranging the program clearly

White space: useful empty space

Indentation

Comments

Meaningful identifiers

Putting the techniques together

You've reached the end

Techniques for readable, maintainable code

What you'll learn

The aim: code that humans can understand

Layout and white space

Layout: arranging the program clearly

White space: useful empty space

Indentation

Comments

Meaningful identifiers

Putting the techniques together

You've reached the end

Techniques for readable, maintainable code

What you'll learn

The aim: code that humans can understand

Layout and white space

Layout: arranging the program clearly

White space: useful empty space

Indentation

Comments

Meaningful identifiers

Putting the techniques together

You've reached the end

Techniques for readable, maintainable code Revision Guide

Techniques for readable, maintainable code

What you'll learn

The aim: code that humans can understand

Layout and white space

Layout: arranging the program clearly

White space: useful empty space

Indentation

Comments

Meaningful identifiers

Putting the techniques together

You've reached the end

Techniques for readable, maintainable code Revision Guide