How Python code is written

What you'll learn

• Read a Python file as a sequence of statements, one per line
• Understand indentation: why it matters, how much to use, and what goes wrong when it is off
• Write comments that help the next reader instead of repeating the code
• Follow the handful of style rules from PEP 8 that every Python developer expects

Concept

A Python program is a list of statements, and by default each line is one statement. Python runs them from the top of the file to the bottom, in order. There are no semicolons to end a line and no braces to group lines. The layout of the text is the structure of the program.

That is the big idea of this lesson: indentation is not decoration in Python, it is syntax. When a statement ends with a colon, such as if, for, or def, the lines that belong to it are indented underneath. Python knows where the block ends when the indentation comes back out. Other languages use braces for this and let you indent however you like; Python removed the braces and made the indentation itself carry the meaning.

The convention, and you should treat it as a rule, is 4 spaces per level. Never tabs, never two spaces, never a mix. Your editor will do this for you when you press Enter after a colon, and VS Code converts the Tab key to four spaces in Python files. Mixing tabs and spaces produces errors that look identical on screen and are miserable to find, so settle this once and never think about it again.

Here is how Python reads a small block: the colon opens it, the indented lines belong to it, and the first line back at the left edge closes it.

Comments start with # and run to the end of the line. Python ignores them entirely; they exist for people. The most useful comment explains why something is done, because the code already shows what is done. A comment that says # add one to count above count += 1 is noise; a comment that says # the API counts pages from 1, not 0 is worth keeping for years.

Blank lines are free and Python ignores them too, so use them the way you use paragraphs in writing: to separate ideas. The style guide, PEP 8, asks for two blank lines between top-level functions and one blank line between logical sections inside a function. Long lines are broken at 79 to 99 characters, and expressions inside parentheses can continue onto the next line without any special marker. Those spacing habits, the four-space indentation from earlier, the naming style snake_case that every Python file uses, and the rule about comments are the whole of this lesson's style guidance, so here they are side by side.

Code

Start with a file that has three things in it: statements, a comment, and a block. The block is an if, which you will learn properly in a few lessons; for now, watch only the shape: the colon, the four spaces, and the line that comes back out.

# shape.py
# Two statements at the top level, then a block.
name = "Mahmud"
print("Start")

if name == "Mahmud":
    print("Inside the block")
    print("Still inside")

print("Back outside")

Start
Inside the block
Still inside
Back outside

Now the mistake this lesson exists to prevent. The second print is indented with two extra spaces, so it does not line up with the block it is supposed to be in. Python refuses to guess and stops before running anything.

# bad_indent.py
name = "Mahmud"

if name == "Mahmud":
    print("Inside the block")
      print("Indented too far")

  File "bad_indent.py", line 5
    print("Indented too far")
IndentationError: unexpected indent

Blank lines and continuation lines are the other half of layout. Both blank lines in this file are ignored, and the long expression is split inside its parentheses without any special character at the end of the first line.

# layout.py
first = 10
second = 20


total = (first
         + second
         + 12)  # the parentheses let the expression continue

print(total)

42

Try it yourself

Open shape.py, delete the four spaces in front of print("Inside the block"), and run it. Read the error message. Put the spaces back, then add a second if block underneath with a different name and two indented prints of your own. Confirm the output shows which lines are inside and which are outside.

Common mistakes

• Mixing tabs and spaces. The editor shows them identically but Python does not, and the result is a TabError or an IndentationError on a line that looks fine. Set your editor to insert four spaces and never touch Tab settings again.
• Forgetting the colon at the end of if, for, or def. Python reports a SyntaxError pointing at the end of that line, and the fix is one character.
• Writing comments that repeat the code. They go stale the first time the code changes, and then they lie. Comment the reason, not the action.

What's next

• A Python file is statements run top to bottom; layout is the structure, and indentation is syntax.
• A colon opens a block, four spaces per level keep it open, and dedenting closes it; never mix tabs and spaces.
• Comments explain why, blank lines separate ideas, and PEP 8 names are lowercase with underscores.

You can now read the shape of any Python file. Next you will fill that shape with values by learning how a program remembers things with variables.