PEP 8 Conventions — Follow PEP 8 style conventions (intro) - Python

SECTION 1

Historical Context & Motivation

Imagine joining a group project where every teammate writes in a different language — one uses Spanish, another uses Mandarin, and a third writes in French. Even if each person's writing is brilliant on its own, the team can't collaborate. Code works the same way. When every programmer formats their Python differently, reading someone else's work becomes frustrating and slow. PEP 8 was created to solve this exact problem by establishing a single, shared style guide for the entire Python community.

The acronym PEP stands for Python Enhancement Proposal, which is the formal process the Python community uses to propose and discuss changes to the language. PEP 8, specifically, is the style guide document that describes how Python code should look. It was written by Guido van Rossum, the creator of Python, along with Barry Warsaw and Nick Coghlan. The guide didn't appear out of nowhere — it grew from years of community discussion about best practices.

1991 • Python Is Born

Guido van Rossum releases Python 0.9.0. Even from the start, Python emphasizes readability as a core design principle, but there is no formal style guide yet.

2001 • PEP 8 Published

Guido van Rossum, Barry Warsaw, and Nick Coghlan publish PEP 8 — the official Style Guide for Python Code. It consolidates years of community conventions into one authoritative document.

2006 • Linting Tools Emerge

Tools like pycodestyle (originally called pep8) begin automatically checking code against PEP 8 rules, making adoption much easier.

2013 • PEP 8 Updated for Python 3

The guide is revised to address Python 3 conventions, including updated naming standards and clarifications on string handling.

2020s • Modern Auto-Formatters

Tools like black and autopep8 can automatically reformat entire codebases to follow PEP 8, making consistent style nearly effortless.

The driving question behind PEP 8 is deceptively simple: How can we write code that other people — and our future selves — can read and understand quickly? As Guido himself wrote, "Code is read much more often than it is written." PEP 8 exists to optimize for that reading experience.

SECTION 2

Core Principles of PEP 8

PEP 8 is a long document with many specific rules, but you don't need to memorize every detail right away. Instead, understanding the core principles behind the rules lets you make good style decisions even when you forget a specific guideline. These principles reflect Python's overall philosophy, which is captured in a fun Easter egg — try typing import this in a Python shell to see "The Zen of Python."

Readability Counts

Code should be written so that a human reader can understand its purpose at a glance. Every formatting choice — spacing, naming, line breaks — should make the logic clearer, not more confusing.

Consistency Matters

Within a project, every file should follow the same conventions. When joining an existing project, match its style even if it differs slightly from PEP 8. Consistency reduces surprise and helps teams move faster.

Explicit Is Better Than Implicit

Your code should clearly show what it does. Use descriptive variable names instead of cryptic abbreviations, and don't rely on tricks that only experts would recognize.

Simple Is Better Than Complex

If two approaches solve the same problem, prefer the one that is easier to follow. Clever one-liners are fun but can confuse anyone reading the code later.

Guidelines, Not Handcuffs

PEP 8 is a guide, not a law. There are times when breaking a rule makes code more readable. The document itself says, "A foolish consistency is the hobgoblin of little minds."

✦

KEY TAKEAWAY

Think of PEP 8 like the rules of the road. Everyone drives on the same side, stops at the same signs, and uses turn signals — not because the law forces you to, but because it keeps everyone safe and moving smoothly. PEP 8 is the traffic system for Python code: it lets thousands of developers collaborate without crashing into each other.

SECTION 3

Visual Explanation — PEP 8 at a Glance

The following diagram shows a side-by-side comparison of the same Python function written two ways. On the left, the code ignores PEP 8 conventions — cramped spacing, poor naming, and inconsistent formatting. On the right, the same logic follows PEP 8 and becomes dramatically easier to read. Pay attention to how spacing, naming, and line length change the experience.

The left panel shows code that works but is hard to read. The right panel applies PEP 8 conventions — descriptive names, consistent spacing, 4-space indentation, and a docstring — making the same logic much easier to understand.

Notice how the right-side version tells a story. You can immediately see that the function calculates a total from a price, quantity, and tax. The 4-space indentation creates a clear visual hierarchy, and the spaces around operators like = and * let your eyes parse each expression without effort. The docstring at the top acts like a label on a file folder, telling you what's inside before you read the details.

SECTION 4

How PEP 8 Works — The Key Rules

PEP 8 covers many aspects of code formatting. While it's not a mathematical framework, it is a structured set of rules that you can learn systematically. Let's break down the most important categories you'll encounter as a beginning Python programmer. Each rule exists to solve a specific readability problem.

Indentation

Python is unique among popular languages because indentation is part of the syntax — it determines which lines belong to which block of code. PEP 8 says to use exactly 4 spaces per indentation level. Never use tabs, and never mix tabs and spaces. Most modern code editors can be configured to insert 4 spaces when you press the Tab key.

Maximum Line Length

PEP 8 recommends keeping lines to a maximum of 79 characters for code and 72 characters for comments and docstrings. This might seem old-fashioned — it comes from the era of 80-column terminals — but it ensures code is readable on split-screen displays, in code review tools, and on smaller laptop screens. When a line is too long, break it using parentheses, brackets, or the backslash character \.

Naming Conventions

How you name things is one of the biggest readability factors in any program. PEP 8 establishes clear patterns for different types of names. Variables and functions use snake_case (all lowercase, words separated by underscores), like student_name or calculate_average. Classes use PascalCase (also called CapitalizedWords), like StudentRecord. Constants use ALL_CAPS with underscores, like MAX_RETRIES.

Whitespace in Expressions

PEP 8 has specific rules about where to add (and not add) spaces. Put one space around assignment and comparison operators (x = 5, if x == 5). Put one space after every comma (print(a, b, c)). Do NOT put spaces immediately inside parentheses (func(arg) not func( arg )) or before a colon in a slice (my_list[1:3] not my_list[1 : 3]).

Imports

Import statements should be placed at the top of the file, after any module comments or docstrings. Each import should be on its own line. Group them in this order: standard library imports, then third-party library imports, then your own local imports, with a blank line between each group.

SECTION 5

Naming Conventions — A Detailed Breakdown

Naming is arguably the most impactful PEP 8 rule. A well-chosen name can replace an entire comment. A poorly chosen name can make correct code look like a bug. The diagram below maps every common Python element to its required naming style, with examples you can reference whenever you write code.

Each card shows a Python element type, its PEP 8 naming convention, and real code examples. The bottom section highlights common mistakes beginners make and how to fix them.

Element	Convention	Good Example	Bad Example
Variable	`snake_case`	`total_score`	`TotalScore`
Function	`snake_case`	`get_average()`	`GetAverage()`
Class	`PascalCase`	`GamePlayer`	`game_player`
Constant	`ALL_CAPS`	`MAX_SPEED`	`maxSpeed`
Module	Short lowercase	`utilities.py`	`MyUtilities.py`

PEP 8 naming conventions for the most common Python elements

SECTION 6

Worked Example — Refactoring Code to Follow PEP 8

Let's walk through a real refactoring exercise. You've been given a working Python function that calculates a student's letter grade, but it violates several PEP 8 rules. Your job is to identify each violation and fix it step by step.

📝

Original Code (Before PEP 8)

def letterGrade(s,Max):
  pct=s/Max*100
  if pct>=90: return 'A'
  elif pct>=80:return 'B'
  elif pct>=70:return 'C'
  else:return 'F'

Refactoring to PEP 8

1
Step 1 — Fix the function name

The function name letterGrade uses camelCase, which PEP 8 reserves for special legacy cases. Functions should use snake_case. The parameter Max starts with a capital letter, which makes it look like a class name. Rename both.

def letter_grade(score, max_score):
2
Step 2 — Fix indentation to 4 spaces

The original code uses 2-space indentation. PEP 8 requires 4 spaces per indent level. Adjust all indented lines.

All body lines now begin with 4 spaces.
3
Step 3 — Add spaces around operators and after commas

The expression pct=s/Max*100 is missing spaces around =, /, and *. Also, the parameter list s,Max needs a space after the comma.

percentage = score / max_score * 100
4
Step 4 — Put each return on its own line

PEP 8 discourages putting the body of an if statement on the same line as the condition. Each return should be on a new, indented line.

Each branch now has the return statement on its own indented line.
5
Step 5 — Add a docstring

PEP 8 (and the related PEP 257) recommends adding a brief docstring as the first line inside every function, explaining what the function does.

"""Return a letter grade based on score and max possible score."""

💡

Final Refactored Code

def letter_grade(score, max_score):
    """Return a letter grade based on score and max possible score."""
    percentage = score / max_score * 100

    if percentage >= 90:
        return 'A'
    elif percentage >= 80:
        return 'B'
    elif percentage >= 70:
        return 'C'
    else:
        return 'F'

The final version is the same logic, but it reads like well-written English. Any programmer — even someone who has never seen this code — can understand it in seconds. That is the power of PEP 8.

SECTION 7

Strengths and Common Pitfalls

PEP 8 is widely praised, but like any set of guidelines, it has both clear strengths and situations where beginners can go wrong. Understanding both sides helps you apply the rules wisely rather than blindly.

Strengths	Common Pitfalls
Makes code readable for anyone in the Python community, not just the original author.	Obsessing over line length at the cost of readability — sometimes 82 characters is clearer than forcing an awkward line break at 79.
Reduces time spent on style debates during code reviews; teams agree on one standard.	Applying PEP 8 inconsistently within a single file, which creates visual noise and is worse than no style at all.
Linting tools can automatically catch violations, so you learn as you code.	Using auto-formatters without understanding the rules — you miss the why behind each convention.
Professional expectation — most Python job listings and open-source projects require PEP 8 compliance.	Prioritizing style over working code — get the logic right first, then polish the formatting.

Balancing the strengths and common pitfalls of PEP 8 adoption

✦

KEY TAKEAWAY

PEP 8 is like proofreading an essay. You wouldn't submit a paper full of random capitalization and missing punctuation, even if the ideas are great. Similarly, clean code formatting shows respect for your reader and lets your logic shine through without distractions. But remember: a perfect first draft isn't the goal. Write working code first, then refine the style.

SECTION 8

PEP 8 and the Broader Python Ecosystem

PEP 8 is just the starting point of Python's style ecosystem. As you grow as a programmer, you'll encounter tools and standards that build on PEP 8's foundation. Understanding where PEP 8 fits in the bigger picture will prepare you for professional development workflows.

Tool / Standard	What It Does	Relationship to PEP 8
`pycodestyle`	Checks your code for PEP 8 violations and reports them line by line.	Direct enforcement of PEP 8 rules. The original PEP 8 checker.
`flake8`	Combines PEP 8 checking with logical error detection and code complexity analysis.	Includes pycodestyle plus additional checks for bugs and complexity.
`black`	An opinionated auto-formatter that rewrites your code to be PEP 8 compliant.	Follows PEP 8 but makes some stricter choices (e.g., 88-char line length).
PEP 257	The companion standard for docstring formatting — how to write help text inside functions and classes.	Extends PEP 8's guidance on documentation strings specifically.
Type Hints (PEP 484)	Adds optional type annotations to function signatures for clarity and tooling support.	A more advanced readability technique that complements PEP 8 naming conventions.

Tools and standards that build on PEP 8

As you advance, you'll likely configure your code editor (like VS Code or PyCharm) to run a linter automatically every time you save a file. This means PEP 8 violations get flagged immediately, just like spell-check underlines misspelled words. Eventually, following PEP 8 becomes second nature — you won't even think about it, much like how you naturally capitalize the first word of a sentence.

ℹ

Looking Ahead

In future lessons, you'll learn how to configure flake8 and black in your projects, write proper docstrings following PEP 257, and use type hints to make your code even more self-documenting. PEP 8 is the essential first step on this journey toward professional-quality Python.

SECTION 9

Practice Problems

Test your understanding of PEP 8 conventions with these five problems. They range from simple identification to critical thinking about when rules should (or shouldn't) be followed.

Question 1: CONCEPTUAL

In your own words, explain why PEP 8 exists. What is the main problem it solves, and who benefits from following it?

Show answer

PEP 8 exists to make Python code consistently readable across the entire community. The main problem it solves is that different programmers naturally format code differently, which makes collaboration and code review harder. Everyone benefits: your teammates can read your code faster, open-source contributors can jump into a new project without re-learning formatting conventions, and even your future self benefits when you revisit code months later. As Guido van Rossum stated, code is read far more often than it is written, so optimizing for the reader is essential.

Question 2: BASIC CALCULATION

Identify all PEP 8 violations in the following code and rewrite it correctly:

def CalcArea(L,W):
  A=L*W
  return A

Show answer

There are five violations: (1) the function name CalcArea uses PascalCase instead of snake_case; (2) the parameters L and W are single uppercase letters — use descriptive lowercase names; (3) no space after the comma between parameters; (4) no spaces around the = and * operators; (5) 2-space indentation instead of 4 spaces. The corrected code is:

def calc_area(length, width):
    """Calculate the area of a rectangle."""
    area = length * width
    return area

Question 3: INTERMEDIATE

A classmate writes the following import section at the top of their file. Rewrite it to follow PEP 8's import guidelines:

import os, sys
from my_module import helper
import numpy
from math import sqrt

Show answer

PEP 8 requires that each import be on its own line, and imports should be grouped: standard library first, then third-party libraries, then local modules, with a blank line between each group. The corrected version is:

import os
import sys
from math import sqrt

import numpy

from my_module import helper

Notice that os, sys, and math are standard library modules (first group), numpy is a third-party library (second group), and my_module is a local module (third group).

Question 4: APPLIED

You are working on a team project for a school science simulation. Your teammate named their variables like this: V (for velocity), A (for acceleration), T (for time), and D (for distance). Rewrite meaningful variable names following PEP 8, and explain why this matters in a collaborative project.

Show answer

Better PEP 8-compliant names would be velocity, acceleration, time_elapsed (avoid just time since it shadows a built-in module), and distance. Single uppercase letters violate PEP 8's naming rules and cause real problems in team projects: a new teammate might not realize A means acceleration versus area, the letter V could mean velocity or voltage, and single letters are nearly impossible to search for in a large codebase. Descriptive snake_case names make the code self-documenting so every team member can contribute without confusion.

Question 5: CRITICAL THINKING

PEP 8 states that its guidelines should sometimes be broken. Describe two specific situations where strictly following PEP 8 might actually make code worse. For each situation, explain what you would do instead and why.

Show answer

First, when you join an existing project that uses a different but consistent style (for example, 2-space indentation from an older codebase), switching only your files to 4 spaces would create inconsistency across the project, which is worse than uniformly using 2 spaces. The better approach is to match the project's existing convention and propose a full-project migration later. Second, the 79-character line limit can sometimes force awkward line breaks in complex expressions or long string literals. For instance, a URL string that is 95 characters long is more readable on one line than split across two lines with string concatenation. In such cases, allowing the longer line (perhaps up to 99 or 119 characters, as many modern teams adopt) improves readability. PEP 8 itself acknowledges this by saying 'a foolish consistency is the hobgoblin of little minds' — the ultimate goal is always readability, and the rules should serve that goal rather than override it.

SUMMARY

PEP 8 Conventions — Summary

Summary

PEP 8 is Python's official style guide, created by Guido van Rossum to ensure that all Python code follows a single, readable format. Its core rules include using 4-space indentation, keeping lines to 79 characters or fewer, using snake_case for variables and functions, PascalCase for classes, and ALL_CAPS for constants. Whitespace rules require spaces around operators and after commas, and imports should be organized at the top of the file in three groups: standard library, third-party, and local.

The overarching principle is that code is read more often than it is written, so every formatting choice should optimize for the reader. Tools like flake8 and black can automatically enforce these rules. However, PEP 8 is a guide, not a law — consistency within a project always takes priority over any individual rule. Mastering PEP 8 early in your coding journey will make your code cleaner, your collaborations smoother, and your transition to professional development much easier.