Elite Coder

Elite Coder Standards

Core Philosophy

Apply these principles in strict priority order:

1. Correctness — Code does what it claims. No silent failures.
2. Clarity — A stranger reads it and understands it immediately.
3. Simplicity — The least code that solves the actual problem.
4. Robustness — Graceful handling of edge cases and bad input.
5. Performance — Fast enough, measured not guessed.

Hard Limits

These are non-negotiable. NEVER violate them.

80 characters max per line

No exception. Break the line. Use intermediate variables, extract helpers, or restructure the expression. Long lines are a code smell indicating excessive nesting or complexity.

20 lines max per function

Count only logic lines (exclude blank lines, docstrings, and the signature). If a function exceeds 20 lines, decompose it. Extract a helper, split the workflow, or rethink the approach.

5 functions max per file

If a module needs more than 5 functions (excluding __init__ and dunder methods), it has too many responsibilities. Split it into focused modules with clear names.

Naming Conventions

• Names reveal intent: remaining_retries not r, is_valid not flag
• Use domain vocabulary: invoice, order, not data, item
• Booleans: prefix with is_, has_, can_, should_
• Functions: strong verbs — parse_config, validate_input, send_notification
• Python: snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE for constants
• No abbreviations unless universally understood (url, id, http)

Function Design

• Single responsibility: one function, one job
• Max 3 parameters: beyond that, use a dataclass or config object
• Guard clauses first: handle invalid cases early with early returns
• Pure functions preferred: same input, same output, no side effects
• 20 lines max: if it does not fit, decompose (see Hard Limits)

# Good: guard clauses + single responsibility
def calculate_discount(price: float, tier: str) -> float:
    if price <= 0:
        raise ValueError("Price must be positive")
    if tier not in DISCOUNT_TIERS:
        raise ValueError(f"Unknown tier: {tier}")

    rate = DISCOUNT_TIERS[tier]
    return round(price * rate, 2)

Error Handling

• Never use bare except: or except Exception:
• Catch specific exceptions: except ValueError, except KeyError
• Fail fast: validate inputs at boundaries, crash early
• Error messages must be actionable: say what went wrong AND what to do
• Use custom exceptions for domain errors

# Bad
try:
    process(data)
except:
    pass

# Good
try:
    process(data)
except ValidationError as e:
    logger.warning("Invalid input: %s", e)
    raise

Code Structure

Python project layout:

project/
  pyproject.toml
  src/
    package/
      __init__.py
      module.py
  tests/
    test_module.py

• Imports: stdlib first, then third-party, then local — separated by blank lines
• No dead code: delete unused functions, commented-out blocks, and TODO-marked stubs
• Max 5 functions per file: split into focused modules (see Hard Limits)
• One class per file when the class is non-trivial

Testing

• Test behavior, not implementation details
• Descriptive names: test_expired_token_returns_401 not test_auth
• AAA pattern: Arrange, Act, Assert — clearly separated
• Cover edge cases: empty inputs, boundaries, error paths
• Reproduce the bug first: write a failing test before fixing

def test_discount_rejects_negative_price():
    with pytest.raises(ValueError, match="positive"):
        calculate_discount(-10, "gold")

Security

• No hardcoded secrets: use environment variables or a vault
• Validate all external input: user data, API payloads, file content
• Parameterized queries: never concatenate SQL strings
• Least privilege: request minimal permissions, scopes, and access

Performance

• Choose the right data structure: set for membership, dict for lookup
• Avoid N+1 queries: batch database calls
• Know your complexity: O(n) vs O(n^2) matters at scale
• Paginate large result sets — never return unbounded lists

Git Discipline

• Atomic commits: one logical change per commit
• Conventional commits: type(scope): description
  • Types: feat, fix, refactor, test, docs, chore
• Never commit: .env, __pycache__, .pyc, IDE configs, build artifacts
• Write meaningful commit messages that explain WHY, not WHAT

Documentation

• Code is self-documenting when names and structure are clear
• Comments explain WHY, never WHAT — the code shows WHAT
• Docstrings for public API only (public functions, classes, modules)
• Keep docstrings concise: one-line summary, then params if needed

def retry(fn, max_attempts=3):
    """Call fn with exponential backoff on failure."""

Self-Review Checklist

Before finalizing any code, verify:

• All lines under 80 characters
• All functions under 20 lines
• All files under 5 functions
• Names reveal intent
• No bare except clauses
• No hardcoded secrets
• Guard clauses used for validation
• Tests cover the happy path and edge cases
• No dead code or commented-out blocks
• Imports are sorted (stdlib / third-party / local)

For detailed conventions, refactoring patterns, and API design guidance, consult references/detailed-guidelines.md.