Check Project Guidelines: Always adhere to AGENTS.md or project-specific instruction documents first.
Keep Sync: If you modify code, updating the associated docstrings is the highest priority. Contradictory docstrings are worse than no docstrings at all. Outdated docstrings are harmful.
Evaluate Necessity (Do not over-document):
- Public APIs (exported modules, classes, functions, public methods) and Complex Logic require docstrings.
- Private APIs and Simple/Self-Documenting Code should omit docstrings or use standard inline comments (#). If a single-line docstring just repeats the function name, delete it. Code clarity through good naming always takes precedence over docstrings.
Component Rules:
- Modules: Provide a high-level overview. Do NOT list members unless required. Often unnecessary unless using code-as-documentation.
- Classes: Summarize behavior. Document constructor (__init__) parameters in the class docstring, NOT in __init__.
- Functions/Methods: Summarize behavior, detail args, returns, and exceptions.
Formatting:
- Single-line: """Summary on one line.""" (Keep """ on the same line, end with period).
- Multi-line: Start with a summary line, a blank line, then details, and close with """ on its own line.
Tone & Doctests:
- Match existing codebase tone (declarative vs. imperative) or fallback to PEP 257 (imperative mood, e.g., "Return X", not "Returns X").
- Doctests are for illustration, not comprehensive edge-case testing.

Advanced References & Templates

Only load these references if you need deeper guidance on a specific topic.

references/evaluation.md: Detailed criteria for when to write docstrings based on exposure and complexity.
references/components.md: Detailed rules on what to document for modules, classes, and functions.
references/formatting_and_tone.md: Detailed rules for single/multi-line formats, doctest philosophy, and voice/tone.

Templates

assets/module_templates.py: Examples of module-level docstrings.
assets/class_templates.py: Examples of class docstrings, including __init__ parameter placement.
assets/function_templates.py: Examples of single-line, multi-line, and private function docstrings/comments.

python-docstring-expert

Python Docstring Expert

Core Guidelines