6.1.4 Readable and maintainable code

Why Code Readability Matters

Code that runs correctly is not necessarily good code. Programs are read many more times than they are written — by the original developer returning to their own work, by colleagues, and by anyone who has to maintain or extend it. Readable code reduces the cost and risk of modification. The techniques below produce code that another programmer (or your future self) can understand without reverse-engineering it.

Five Techniques

Indentation shows the structure of code visually — which statements belong inside a loop or if block. In Python it is mandatory (incorrect indentation causes an error); in C# and VB.NET it is convention.

# Poor indentation (valid Python only by accident — bad practice)
for i in range(3):
 if i > 1:
  print(i)

# Clear indentation
for i in range(3):
    if i > 1:
        print(i)

Consistent 4-space indentation (Python convention) makes nesting depth immediately clear.

Comments explain the why, not the what — a reader can see what code does by reading it; comments explain the reasoning and context. A comment that just repeats the code adds noise; a comment that explains intent adds value.

# Poor comment — just restates the code
count = count + 1   # add 1 to count

# Useful comment — explains why
count = count + 1   # increment attempt counter; lock after MAX_ATTEMPTS

# Docstring comment for a function
def calculate_vat(price):
    """Returns the VAT-inclusive price at the standard 20% rate."""
    VAT_RATE = 0.20
    return price * (1 + VAT_RATE)

Meaningful identifiers (variable, function and constant names) make code self-documenting. A reader should be able to understand the purpose of a variable from its name alone, without needing a comment to explain it.

# Poor identifiers — meaningless
x = 3.14159
def c(r):
    return x * r * r

# Meaningful identifiers
PI = 3.14159
def circle_area(radius):
    return PI * radius * radius

Convention: snake_case for variables and functions in Python; PascalCase for classes; ALL_CAPS for constants.

White space (blank lines and spaces) separates logical sections of code, making transitions and groupings visible. Operators surrounded by spaces are easier to read than code crammed together.

# Without white space — dense and hard to parse
def get_discount(price,is_member):
    RATE=0.10
    if is_member:return price*(1-RATE)
    else:return price

# With white space — clear and readable
def get_discount(price, is_member):
    RATE = 0.10
    if is_member:
        return price * (1 - RATE)
    else:
        return price

Layout refers to the overall organisation of a program: grouping related code, placing constants at the top, keeping functions together, and structuring a program so the main logic is easy to locate.

# Good layout: constants first, functions defined before use, main at end

# Constants
MAX_SCORE = 100
PASS_MARK = 60

# Functions
def is_pass(score):
    """Returns True if score meets the pass mark."""
    return score >= PASS_MARK

def grade(score):
    """Returns a letter grade based on score."""
    if score >= 80:
        return "A"
    elif score >= 60:
        return "B"
    else:
        return "F"

# Main program
student_score = int(input("Enter score: "))
print("Pass:", is_pass(student_score))
print("Grade:", grade(student_score))

Key Takeaways

Indentation: shows code structure visually; mandatory in Python.
Comments: explain why, not what; use docstrings for functions.
Meaningful identifiers: circle_area(radius) is better than c(r).
White space: spaces around operators and blank lines between sections improve readability.
Layout: constants at the top, functions before main, related code grouped together.