google / google/styleguide

Feature Request: LLM-optimized version of the style guide

Open
#970 5 comments 2 reactions 1 assignee Claimed by @nathanielmanistaatgoogle View on GitHub
Dominant language
HTML
Stars
39.6k
Forks
12.9k
Avg merge
42m
Merged PRs (30d)
15

Description

### 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.