Can you read this?
Here is a line from a real program: x = a * b - c.
What is x? What are a, b and c? Nobody knows. The writer will not remember in six months.
Now read this: final_price = price * quantity - voucher. You understand it at once. The same code is easy to read when it follows good habits.
Key words
| Word | What it means | Example |
|---|---|---|
| Voucher | A code or ticket that takes money off the price. | 5 pounds off |
| Variable | A name that holds a value. | price |
| Function | A named block of code that does one job. | total_price() |
| Constant | A value that never changes while the program runs. | MAX_SIZE |
| Convention | A habit that a whole team agrees to follow. | |
| Naming convention | Rules for how to write the names of variables and functions. | total_price |
| camelCase | A style where words are joined and each new word starts with a capital. | totalPrice |
| Comment | A note in the code for people. The computer ignores it. | # add the tax |
| Docstring | A note in triple quotes inside a function. It says what the function does. | |
| Modular | Built from small separate parts, each with one job. | |
| Indentation | Spaces at the start of a line. They show which lines belong together. | |
| Readability | How easy the code is to read. | |
| Maintainability | How easy the code is to change later. | |
| Version control | A tool that keeps every version of your files. |
The cells students fill in are left blank in this preview.
Names that say what things are
A good name tells the reader what a value is or what a function does.
Use whole words: average_mark, not am. Use a verb for a function: calculate_total. Use a noun for a value: price.
A team also agrees one style. That is the naming convention.
Try it: before and after
# BEFORE: it works, but it is hard to read
def f(a,b):
x=0
for i in a:
x=x+i
return x-b
# AFTER: the same job, easy to read
def total_price(prices, voucher):
"""Add up the prices and take off the voucher."""
total = 0
for price in prices:
total = total + price
return total - voucher
print(f([5, 3, 2], 4))
print(total_price([5, 3, 2], 4))
Common naming styles
| Style | Looks like | Often used for |
|---|---|---|
| snake_case | total_price | Python variables and functions |
| camelCase | totalPrice | JavaScript and Java variables and functions |
| PascalCase | TotalPrice | Classes in most languages |
| UPPER_CASE | MAX_SIZE | Constants: values that never change |
The cells students fill in are left blank in this preview.
Spot the bad code
Have a go
Spot the bad code
4 questionsYour answers are marked here and are not kept. A college account keeps every student’s marks.
Comments: say why, not what
A comment is a note for people. The computer ignores it.
Do not repeat the code. # add 1 above count = count + 1 says nothing new. Say why: # the first row is the header, so skip it.
A docstring goes inside a function and says what it does and what it gives back.
Small parts and clear layout
Modular code is made of small functions. Each does one job. You can test each one. You can reuse it.
Good structure helps too. Put imports at the top, then constants, then functions. Use the same indentation everywhere. Python uses four spaces. In Python it is not only style: the indentation is part of the language.