Reviewing a small change: Free Lesson

Two pairs of eyes

A colleague has written a refund rule for a delivery app. Before it goes live, they ask you to look at it.

You are new, and they have been here three years. Your review still matters. A fresh reader spots what the writer stopped seeing.

By the end of this lesson

Note

I can review a small change and say what to improve.

Key words

Word	What it means
Code review	reading a colleague's change before it is accepted
Change	the lines added, edited or removed in one piece of work
Reviewer	the person who reads and comments on a change
Edge case	a value at a limit, where bugs often hide
Comment	a note the reviewer leaves on one line of the change

The cells students fill in are left blank in this preview.

A review asks three questions

Read the change once to see what it is for. Then ask three questions.

Does it work? Try the edge cases. Can someone else read it? Look at the names. Is anything missing? Look for a test, or a case nobody handled.

You do not need to know the whole codebase to ask these.

Try it: run the change

Code: python

# The change under review: a refund rule for a delivery app.

def r(o, d):
    # o is the order total in pence, d is minutes late.
    if d > 30:
        return o
    if d > 10:
        return o // 2
    return 0


print(r(2000, 45))
print(r(2000, 20))
print(r(2000, 5))

# Try r(2000, 30) and r(2000, 10).
# Are those the refunds the rule should give? Write down what you would ask.

Good names explain the code

A name is read far more often than it is written. r(o, d) makes every reader work out what each letter means.

refund_for_late_delivery(order_total, minutes_late) says it straight away. Ask for names that say what a thing is or does.

Practise: choose a clear name

Code: python

def refund_for_late_delivery(order_total, minutes_late):
    # Over 30 minutes late: full refund. Over 10 minutes: half.
    if minutes_late > 30:
        return order_total
    if minutes_late > 10:
        return order_total // 2
    return 0


print(refund_for_late_delivery(2000, 45))

# Rename refund_for_late_delivery to something shorter but still clear.
# Change the print line too, then press Run.

A good comment is kind and specific

Comment on the code, never the person. Say which line, what you noticed and why it matters. Ask a question when you are not sure.

Say what is good, too. The writer then knows what to keep.

Worked example: weak and useful comments

Weak comment	Useful comment
This is wrong.	Line 5: at exactly 30 minutes this gives half. Should 30 be a full refund?
Bad names.	Could r be refund_for_late_delivery? I had to read the body to understand it.
Why no tests?	Could we add a test for 10 and 30 minutes? Those are the edges.
LGTM	The early return makes this easy to follow. Nice.