Lesson 32 · Designing code

Clean code

Code is read far more often than it is written, so good code is written for the next person who reads it. Take a messy 10-line Python function and clean it up one change at a time: say each rule once, follow PEP 8, choose clear names, name the magic numbers, write comments that say why, and give each function one job. Tests prove every answer stays the same; then one deliberate fix makes bad input fail loudly.

12 min10 steps5 questionsIntermediate

Fig 32 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01What does refactoring mean?

A refactor changes the shape of the code (names, layout, structure) but every input still gives the same answer. Tests are how you check that.

02Why write tests before you start refactoring?

The three carts gave 108.0, 60 and 112.5 before any change. Running the same tests after each change shows the behaviour did not move.

03In total *= 1.2, why is 1.2 called a magic number?

A named constant, TAX_RATE = 0.20, says what the number means and keeps it in one place. PEP 8 writes constants in capital letters.

04Which comment is most useful?

Good comments explain why the code is the way it is. The others only repeat what the code already says, which PEP 8 calls distracting.

05After the refactor, subtotal raises ValueError for a negative qty. Why is that a separate step?

Errors should never pass silently (PEP 20). But raising an error is new behaviour, so it is a fix, made after the refactor and checked by its own new test.

Key terms

Glossary

Clean code: Code that is easy for a person to read, understand and change: clear names, small functions, no surprises.
Refactoring: Changing the structure of code without changing what it does. Every input still gives the same output.
Test: A small program that calls your code with known inputs and checks it gives the expected answers.
PEP 8: Python's official style guide: spacing, names, line length and more, so all Python code looks alike.
Magic number: A bare value in code, like 1.2 or 100, with no name to say what it means.
Constant: A name for a value that does not change, written in capitals in Python, such as TAX_RATE = 0.20.
DRY: Don't repeat yourself: each rule or piece of knowledge should be written in exactly one place.
Exception: Python's way of signalling an error, such as ValueError. Raising one stops the function and reports the problem.

Fine print

Notes and sources

The refactor keeps the behaviour for the inputs the function is meant for: add_tax is True or False, and every item is a (price, qty) pair. For other values the two forms can differ (with add_tax = "yes", t == True is False but if add_tax: is true).
x *= 1.2 gives the same result as x = x * 1.2, and 1 + 0.20 is exactly the same float as 1.2, so every answer matches to the last digit. Each version on the card is checked with python3.
for price, qty in items unpacks each pair, just like l[i][0] and l[i][1]. One small difference: unpacking raises an error if an item has more than two parts, where indexing would ignore the extra.
Raising ValueError is a fix, not a refactor: a negative qty used to give a negative total (-10) and now stops with an error. That is why it comes last, with its own test.

Quiz Unlocks after the last step.