Skip to content

Feature Request: LLM-optimized version of the style guide #970

@whoiam1101

Description

@whoiam1101

Problem

The current Python Style Guide is ~23,000 tokens when used as context for LLM tools (Continue.dev, Cursor, GitHub Copilot, system prompts, etc.). This is impractical:

  • Consumes a large portion of the context window
  • Significantly increases cost per request
  • The verbose Pros/Cons/Definition structure is useful for humans but redundant for LLMs

Proposal

Add an official LLM-friendly version of the style guide — a compact, rule-dense summary that can be dropped directly into:

  • A system prompt
  • An IDE rules file
  • Any LLM context window

The format should be:

  • Decision/rule only — no Pros/Cons/Definition sections
  • Structured for machine consumption (concise bullet points, minimal prose)
  • Kept in sync with the main guide

Example

The existing guide section on exceptions is ~900 tokens. The LLM-optimized equivalent:

## Exceptions
- Raise built-in exceptions for programming mistakes: `ValueError` for precondition
  violations, `TypeError` for wrong types — not custom ones
- Custom exceptions: inherit from existing exception class, name ends in `Error`,
  no repetition (`foo.FooError` → bad, `foo.Error` → ok)
- Never `except:` or `except Exception` or `except StandardError` unless:
  - re-raising the exception, OR
  - isolation point (e.g. top of thread) where exception is logged and suppressed
- No `assert` for application logic or precondition enforcement — assert can be
  disabled with `-O` flag. OK only in pytest tests and non-critical post-conditions
- Minimize code in `try` block — only the line that can actually raise
- Always use `finally` for cleanup (closing files, releasing locks, etc.)
- Raise exceptions with context: `raise ValueError(f"Min port must be >= 1024, got {val}")`
- Do not raise `Exception` or `BaseException` directly
- Exceptions in `Raises:` docstring section: only document explicitly raised ones,
  not indirect ones from called functions

~250 tokens. Same actionable content.

This would make the Google Python Style Guide directly usable in modern AI-assisted development workflows without manual summarization.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions