ALL-NAMI0001 · uninformative_local_name

Count local names too short to say what they hold.

This is a deterministic rule for all languages. Read its implementation.

Definition

Read every name one declaration binds and report one shorter than minimum_length that is not a conventional index or a loop counter. A local name is the cheapest documentation a body has and the only one that cannot go stale, so a body that binds d, r, and tmp has spent that budget on nothing and made every later line ambiguous.

Only a callable is judged. A field on a type is part of an interface its readers meet by name elsewhere, so id on a model reads fine where id inside a function body does not.

This is the first rule to read code rather than counts. It receives the declaration’s own tree and its exact source, which is what lets it ask about spelling at all.

Evidence

Each finding names the declaration that holds the binding, the name itself, the line it sits on, and how many characters short of readable it is. The repair is a choice, because only the author knows what the value holds. The value is the number of uninformative bindings.

Exceptions

A single-letter index in a comprehension or a short loop is a convention older than the code and reads fine, so i, j, k, n, and x through z are left alone. A field declared on a type is not a local and is not judged. A name whose scope is one line is arguably fine too, which is why the ceiling is a setting rather than a rule.

Examples

Bad

def load(path):
    d = read(path)
    r = parse(d)
    return r

Good

def load(path):
    raw = read(path)
    return parse(raw)

References

• Cites “Clean Code”, chapter 2, meaningful names
• Cites “Code Complete”, chapter 11, the power of variable names
• Cites “PEP 8, Style Guide for Python Code”, naming conventions. Open reference