evilissimo/naming-things
Reviews and improves **names** in code — variables, functions, classes, modules, parameters — for clarity, intent, and consistency with language/team conventions. Triggers when asked to review names, rename things, improve code readability, clean up confusing code, or when examining code with generic/vague names like "data", "info", "manager", "temp", "util". Does NOT trigger for general code review unrelated to naming, architecture design, debugging, or performance optimization. Identifies naming anti-patterns (generic names, misleading names, type-encoding, abbreviations), suggests role-based names that reveal intent, checks consistency with project/domain vocabulary, and flags misalignment with language culture.
91
90%
Does it follow best practices?
Impact
94%
1.05xAverage score across 5 eval scenarios
Passed
No known issues
python.mdreferences/
Python Naming Conventions
Based on PEP 8 — the official Python style guide.
Convention Table
| Thing | Convention | Example |
|---|---|---|
| Variable | snake_case | user_name, total_count |
| Function / method | snake_case | calculate_total(), get_user() |
| Class | PascalCase | CustomerOrder, HttpClient |
| Module | snake_case | order_processing.py |
| Package | snake_case (no hyphens) | my_package/ |
| Constant | SCREAMING_SNAKE_CASE | MAX_RETRY_COUNT, DEFAULT_TIMEOUT |
| Private (by convention) | Prefix _ | _internal_helper() |
| Name-mangled (class-private) | Prefix __ | __private_method() |
| "Magic" / dunder | __dunder__ | __init__, __str__ |
Key Points
- Avoid single-letter names except for: loop counters (
i,j,k), coordinates (x,y), mathematical indices (n,m) - Don't use Hungarian notation — Python has dynamic types,
strNameis noise - Boolean variables: use
is_,has_,can_prefixes:is_active,has_permission,can_edit - Functions should be verbs:
save_record(), notrecord_saving() - Classes should be nouns:
Customer, notCustomerManagement - Exceptions should end in
Errorunless they're truly exceptional:ValidationError,NotFoundError - Avoid names that shadow built-ins: don't name variables
list,dict,str,int,file,type,id - Double-underscore name mangling (
__private) is for subclass safety, not general privacy — prefer single_
Common Offenses
| Bad | Good | Reason |
|---|---|---|
val / vals | value / values | Unnecessarily abbreviated |
data | orders, users, results | Too generic — what data? |
do_stuff() | process_payment(), send_email() | Hides what it does |
temp | scratch_dir, buffer, workspace | Name by role, not lifespan |
handler, manager, controller | PaymentHandler, SessionManager, OrderController | OK for well-known patterns (keep the role) |
lambda x: x[0] | give x a meaningful name in the context | Destructuring helps readability |