Documentation drift is silent. Your code ships, your docstrings stay behind,
and six months later a new developer reads this:
def calculate_discount(price: float, rate: float = 0.1) -> float:
"""Calculate discount.
Args:
price (float): Price of the object.
rate (float): Rate of the object.
Returns:
float: Description of the return value.
"""
return price * (1 - rate)
Technically documented. Completely useless.
The real problem with AI-generated docstrings
AI tools are great at filling the blank — they will generate something for
every function. But "something" is not the same as "accurate." The moment you
rename a parameter, change a return type, or add a new exception, the docstring
is already wrong. There is no enforcement. There is no drift detection.
You end up with documentation that passes a quick glance but fails the developer
who actually needs it.
What deterministic validation gives you
PyCodeCommenter takes a different
approach — rule-based, AST-driven, no external API calls. It does three things:
Generate — produces a starter docstring from the actual function signature:
pycodecommenter generate main.py -i
Validate — checks six things against the real code:
- Parameters in the docstring match parameters in the signature
- Type hints match documented types
- Raised exceptions are documented
- Return values are documented
- Format follows Google-style guidelines
- No placeholders or TODOs left behind
pycodecommenter validate main.py
Coverage — gives you a project-wide documentation score:
pycodecommenter coverage ./src
Where it fits in a real workflow
The most useful place is a pre-commit hook or CI step — not as a blocker on
day one, but as a signal:
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: validate-docstrings
name: Validate Docstrings
entry: pycodecommenter validate .
language: system
types: [python]
Or in GitHub Actions:
- name: Validate documentation
run: pycodecommenter validate .
Now documentation drift gets caught at the PR stage, not six months later.
The new --dry-run flag (v2.1.0)
The latest release adds a safety flag that shows you exactly what would change
before touching any file:
pycodecommenter generate main.py --dry-run
Prints a unified diff to stdout. Exit code 1 if changes exist, 0 if clean —
CI-friendly by design.
Combined with --backup:
pycodecommenter generate main.py -i --backup
Saves main.py.bak before any in-place write. No more accidental overwrites.
Configuration
Drop a .pycodecommenter.yaml in your project root:
style: google
validation:
level: strict
check_types: true
check_exceptions: true
coverage:
threshold: 80
fail_below: true
exclude:
- "*/tests/*"
- "*/migrations/*"
Try it
pip install pycodecommenter
pycodecommenter generate your_file.py --dry-run
The project is open source under MIT.
GitHub: AmosQuety/PyCodeCommenter
Built by Nabasa Amos — a software engineer
focused on developer tooling and open source.
Top comments (0)