Whose code is this?

It is your first week at a company. You open a file written by somebody who left. One part is 200 lines long. The names are a, b and x2. There are no comments.

You must fix a bug in it by Friday. How do you feel?

People read code many more times than they write it. So we write code for the next reader.

Key words

Word	What it means	Example
Modular	Made of small parts. Each part does one job.	line_total, receipt_line
Readability	How easy it is for a person to read and understand the code.	Clear names
Convention	A rule that most programmers in a team or language follow.	snake_case names in Python
camelCase	A way to write names: new words start with a capital letter and there is no space.	totalPrice
Comment	A note in the code for people. The computer ignores it.	# Add the delivery fee
Change log	A list of what changed in each version.	2.0.1 Fixed the login bug
Documentation	Written help about the code and the product.	A README file
Refactoring	Changing the code to make it cleaner, without changing what it does.	Split one long function into three
Function	A named piece of code that does one job.	line_total(price, qty)

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

Five habits of a good team member

Habit	What it means	Example
Separate the code (modularity)	Small parts, each with one job	Do not put the price sum and the printing in one function
Make it readable	Names and layout that explain themselves	total_price, not tp
Follow conventions	Do what the language and the team do	snake_case in Python, one style in the team
Comment to explain why	Say why, not what	# Free delivery starts at 20 because of the offer
Update the change log and documents	Record every change	Write a line in the change log with each fix

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

Try it: the same code, two ways

Code: python

# Version 1
def f(a, b):
    return a * b * 0.8

print(f(10, 3))

# Version 2
def discounted_price(price, quantity):
    # Members get 20 out of every 100 off, so we keep 80 out of 100 (0.8).
    member_share = 0.8
    return price * quantity * member_share

print(discounted_price(10, 3))

# Both print 24.0. Which would you rather maintain?

Conventions are about agreement

data-callouts.tip.label

Python programmers write names in snake_case: small letters with underscores, like total_price. Java programmers use camelCase: new words start with a capital letter and there is no space, like totalPrice. Neither is better. What matters is that the whole team does the same.

Comments that help

A comment is a note for people. The best comments say why. The code already says what.

Bad: # multiply price by quantity. Good: # Round up, because the shop never sells half a unit.

A wrong comment is worse than no comment. When you change the code, change the comment. Notes in code are also called annotations.

Try it: a note inside a function

Code: python

def line_total(price, quantity):
    """Give back the price times the quantity."""
    return price * quantity


print(line_total(2.5, 2))
print(line_total.__doc__)

# The text in triple quotes is a docstring: a note that stays with the function.
# Change the note, and run again.