Introduction
A guide to writing beautiful, readable, and professional Python code
Writing clean and readable code is essential for collaboration, maintenance, and debugging. Python promotes readability through its official style guide, PEP8 (Python Enhancement Proposal 8). This module will walk you through the core PEP8 guidelines and best practices to help you write code that looks good and makes sense to others (and your future self).
Why Code Style Matters
- Readability: Clear formatting and naming make code easier to understand.
- Consistency: Consistent style reduces cognitive load when switching between projects.
- Collaboration: Well-formatted code is easier to review, debug, and maintain in teams.
- Professionalism: Clean code reflects good discipline and professionalism.
Formatting and Layout Rules
Indentation
Use 4 spaces per indentation level. Avoid using tabs.
def greet(name):
print("Hello,", name)Maximum Line Length
Keep lines under 79 characters. For docstrings or comments, aim for 72 characters.
# This is a comment that follows the recommended line length guidelines.Line Breaks
Use blank lines to separate:
- Functions and class definitions
- Logical sections of code inside a function
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Variable | lower_case_with_underscores | user_name |
| Function | lower_case_with_underscores | calculate_total() |
| Class | CapitalizedWords | UserProfile |
| Constant | ALL_CAPS_WITH_UNDERSCORES | MAX_RETRIES |
🚫 Avoid single-letter variable names unless used in short loops.
Writing Comments and Docstrings
Inline Comments
Should be brief and start with a #, with one space after it.
x = x + 1 # Increment x by 1Block Comments
Use for longer explanations before code blocks. They should be indented at the same level as the code.
Docstrings
Use triple quotes to describe functions, classes, or modules.
def multiply(a, b):
"""Returns the product of two numbers."""
return a * bSpacing Rules
- No extra spaces around
=when used for keyword arguments or default values. - One space around binary operators (
+,-,=, etc.) - No space between a function name and its opening parenthesis.
# Correct:
total = a + b
def greet(name):
# Incorrect:
total=a+b
def greet (name):Tools for Code Style and Formatting
- Black – The uncompromising code formatter.
- flake8 – Checks your code against PEP8 and detects style violations.
- pylint – Linter that also checks for code smells and possible bugs.
- isort – Automatically sorts your Python imports.
💡 Most IDEs like VS Code and PyCharm support these tools with extensions or built-in integrations.
💡 Pro Tips
- Use consistent indentation throughout the project.
- Use descriptive names instead of short unclear ones.
- Keep functions small and focused on a single task.
- Don’t over-comment obvious code; comment why, not what, when possible.
- Break long logic into smaller helper functions.
- Run your code through a formatter like
blackbefore finalizing.
📌 Challenge Exercise:
Take one of your older Python scripts and refactor it using PEP8 guidelines. Use flake8 or black to identify and fix violations.