readable-py

Readable Python Rules (/readable-py)

Apply these rules when writing, reviewing, or refactoring Python code. Inspired by The Art of Readable Code by Dustin Boswell and Trevor Foucher.

Core principle: Code should be easy to understand. The time it takes someone else (or future you) to understand the code is the ultimate metric.

1. Keep Functions Short and Focused

• A function should do one thing. If you can describe what it does with "and", split it.
• Aim for functions that fit on one screen (~15-25 lines). If it's longer, extract sub-tasks.
• Each function should operate at a single level of abstraction — don't mix high-level logic with low-level details in the same function.

2. Flatten Control Flow — No Deep Nesting

• Never nest more than 2 levels deep. If you have a loop inside a loop, or an if inside a loop inside an if, extract the inner block into a helper function with a descriptive name.
• Use early returns / guard clauses to handle edge cases at the top, keeping the main logic flat.
• Prefer continue or break to skip iterations rather than wrapping the body in a conditional.
• Replace complex conditionals with well-named helper functions or variables that explain the intent.

# Bad: nested and hard to follow
for user in users:
    if user.is_active:
        for order in user.orders:
            if order.is_pending:
                process(order)

# Good: flat, each function name explains what it does
active_users = get_active_users(users)
for user in active_users:
    process_pending_orders(user.orders)

3. Name Things Clearly

• Pack information into names. Use specific, concrete words — fetch_page not get, num_retries not n.
• Avoid generic names like tmp, data, result, val, info, handle — unless the scope is tiny (2-3 lines).
• Use names that can't be misconstrued. If a range is inclusive, say max_items not limit. If a boolean, use is_, has_, should_, can_ prefixes.
• Match the name length to the scope. Short names for small scopes, descriptive names for wide scopes.
• Don't use abbreviations unless they're universally understood (num, max, min, err are fine; svc_mgr_cfg is not).

4. Make Control Flow Easy to Follow

• Put the changing/interesting value on the left side of comparisons: if length > 10 not if 10 < length.
• Order if/else blocks: positive case first, simpler case first, or the more interesting case first.
• Minimize the number of variables the reader has to track. Reduce the mental footprint of each block.
• Avoid the ternary operator for anything non-trivial — if it's not immediately obvious, use an if/else.

5. Break Down Giant Expressions

• Use explaining variables to break complex expressions into named pieces.
• Use summary variables to capture a long expression that's used more than once.
• Apply De Morgan's laws to simplify negated boolean expressions.

# Bad
if not (age >= 18 and has_id and not is_banned):
    deny()

# Good
is_eligible = age >= 18 and has_id and not is_banned
if not is_eligible:
    deny()

6. Extract Unrelated Subproblems

• If a block of code is solving a subproblem unrelated to the main goal of the function, extract it.
• The helper function should be pure and self-contained — it shouldn't need to know about the calling context.
• This is the single most effective way to improve readability: separate what you're doing from how.

7. One Task at a Time

• Each section of code should do one task. If a function is doing parsing AND validation AND transformation, split them into separate steps.
• List the tasks a function does. If there's more than one, reorganize so each task is in its own block or function.

8. Reduce Variable Scope

• Declare variables close to where they're used. Don't declare at the top of a function if it's only used 30 lines later.
• Minimize the "live time" of a variable — the fewer lines between its assignment and last use, the easier it is to follow.
• Prefer write-once variables. Variables that are assigned once and never modified are easier to reason about.
• Eliminate unnecessary variables. If a variable is used only once and doesn't clarify anything, inline it.

9. No Magic Numbers or Strings

• Replace magic numbers and strings with named constants: if retries > MAX_RETRIES not if retries > 3.
• If a value has meaning, give it a name. The name documents the intent.
• Group related constants together.

10. Fewer Function Arguments

• Aim for 3 or fewer arguments per function. More than that is a smell.
• Group related arguments into an object, dataclass, or named tuple.
• If a function needs many config-like options, pass a single config/options object.
• Boolean flag arguments are a sign the function does two things — split it instead.

11. Consistency

• If the codebase does something one way, do it the same way. Don't mix styles.
• Consistent naming patterns, consistent structure, consistent error handling.
• When joining an existing codebase, match the existing conventions even if you'd prefer a different style.
• Surprise is the enemy of readability — predictable code is readable code.

12. Write Less Code

• The best code is no code at all. Question whether a feature is truly needed before implementing.
• Don't over-engineer. Solve the problem at hand, not hypothetical future problems.
• Remove dead code. Commented-out code is dead code.
• Use standard libraries before writing custom solutions.

13. Comments: Explain Why, Not What

• Don't comment what the code does — the code already says that. Comment why it does it.
• Comment flaws and workarounds: // TODO:, // HACK:, // XXX: with explanation.
• Comment surprising behavior or non-obvious decisions — things where a reader would ask "why?".
• Don't comment bad code — rewrite it. If you need a comment to explain what a block does, extract it into a well-named function instead.

14. Design Code to Survive Auto-Formatting

• Write code that looks good after the auto-formatter runs. If a chained expression or repeated pattern would be broken across 4+ lines by the formatter, extract a helper function instead.
• Prefer one-line helper calls over long inline chains that the formatter will expand vertically.
• The formatter is your reader's first impression. Run it before committing — if the result looks ugly, that's a signal to refactor, not to disable the formatter.

# Bad: black wraps this into a multi-line mess
result = (
    client.get_session()
    .query(User)
    .filter(User.active == True)
    .options(joinedload(User.orders))
    .order_by(User.created_at.desc())
    .limit(page_size)
    .all()
)

# Good: extract a helper so the call site stays clean
def get_active_users(session, page_size: int) -> list[User]:
    return (
        session.query(User)
        .filter(User.active == True)
        .options(joinedload(User.orders))
        .order_by(User.created_at.desc())
        .limit(page_size)
        .all()
    )

users = get_active_users(client.get_session(), page_size=20)

# Bad: dict comprehension with inline chain — black expands to 5+ lines
config = {
    k: settings.get(k, defaults.get(k, fallbacks.get(k, None)))
    for k in required_keys
}

# Good: extract the lookup
def resolve_setting(key, settings, defaults, fallbacks):
    return settings.get(key, defaults.get(key, fallbacks.get(key)))

config = {k: resolve_setting(k, settings, defaults, fallbacks) for k in required_keys}

---

Python-Specific Rules

15. Prefer Comprehensions — But Keep Them Simple

• Use list/dict/set comprehensions for simple transforms and filters.
• If a comprehension needs a nested loop AND a conditional, it's too complex — use a regular loop or extract a helper.
• Generator expressions for large sequences to avoid materializing the whole list.

# Good: simple and readable
names = [user.name for user in users if user.is_active]

# Bad: too much going on
result = [transform(item) for group in data for item in group.items if item.valid and item.type == "A"]

# Good: break it up
valid_items = get_valid_items(data, item_type="A")
result = [transform(item) for item in valid_items]

16. Use Unpacking

• Tuple unpacking over index access: name, age = get_user() not result[0], result[1].
• Star unpacking for head/tail: first, *rest = items.
• Dict unpacking with ** for merging dicts.
• Unpacking makes the structure of the data explicit in the code.

17. Use enumerate, zip, and Itertools

• Use enumerate(items) — never track indices manually with i += 1.
• Use zip(a, b) to iterate in parallel — never index into parallel lists.
• Use itertools (chain, groupby, islice) before writing manual iteration logic.

18. Use Dataclasses and NamedTuples Over Raw Dicts/Tuples

• If a dict always has the same keys, it should be a dataclass or NamedTuple.
• If a function returns more than 2 values, return a dataclass or NamedTuple — not a raw tuple.
• This gives you names, type hints, and readable attribute access for free.

19. Use pathlib for File Paths

• Use pathlib.Path instead of os.path.join and string manipulation.
• Path objects are readable, composable (/ operator), and cross-platform.