당신의 docstrings가 거짓말을 하고 있습니다 — docvet 1.14가 잡아냅니다

Source: Dev.to

Overview

2024년 연구인 Macke & Doyle에 따르면 잘못된 문서는 LLM 작업 성공률을 22.6 퍼센트 포인트만큼 낮춘다고 합니다. 문서가 전혀 없을 때는 통계적으로 유의미한 영향을 미치지 않으며, 이는 AI 코딩 어시스턴트가 잘못된 문서가 전혀 없는 경우보다 성능이 더 떨어진다는 뜻입니다.

Docvet은 이러한 격차를 메웁니다. v1.14에서는 단순히 docstring이 존재하는지 확인하는 것을 넘어, docstring이 코드와 일치하는지도 검증합니다.

Background

Docvet의 초기 초점은 존재 여부 검사—docstring에 행동이 언급되어 있는지 확인—였습니다. 버전 1.14에서는 역방향 검사를 추가했습니다: “docstring이 코드가 구현하지 않은 행동을 주장하고 있는가?”

What’s new in docvet 1.14

Parameter agreement

두 개의 새로운 규칙이 Args: 섹션과 함수 시그니처를 매개변수별로 비교합니다:

• missing‑param‑in‑docstring – 시그니처에 존재하지만 docstring에 누락된 매개변수를 표시합니다.
• extra‑param‑in‑docstring – Args:에 문서화되어 있지만 시그니처에 없는 매개변수를 표시합니다.

Example

src/client.py:47: missing‑param‑in‑docstring
Function 'connect' has parameters not documented in Args: max_retries [required]

Docvet은 위치 전용 매개변수(PEP 570), 키워드 전용 매개변수를 처리하고 self/cls는 제외합니다. Google 및 Sphinx docstring 스타일 모두를 지원합니다.

Reverse behavior checks

세 개의 새로운 규칙이 코드가 전혀 구현하지 않은 행동을 설명하는 문서를 감지합니다:

• extra‑raises‑in‑docstring – 함수가 절대 발생시키지 않는 예외를 문서화합니다.
• extra‑yields‑in‑docstring – 비‑제너레이터 함수에서 yield 문을 문서화합니다.
• extra‑returns‑in‑docstring – 함수가 절대 반환하지 않는 값을 문서화합니다.

Pitfall: 함수가 FileNotFoundError를 전혀 발생시키지 않는데 docstring에 해당 예외가 명시되어 있으면 호출자는 불필요한 try/except 블록을 작성하게 되고, AI 도구는 불가능한 오류에 대비한 방어 코드를 생성할 수 있습니다.

Trivial docstring detection

trivial‑docstring 규칙은 심볼 이름과 요약을 단어 집합으로 분해하고 불용어를 필터링한 뒤, 요약이 이름을 단순히 반복하는 경우를 표시합니다.

def get_user():
    """Get user."""

이 경우 존재 여부 검사는 통과하지만 실제 정보는 제공하지 않습니다.

Deprecation and return‑type checks (opt‑in)

• missing‑deprecation – warnings.warn(DeprecationWarning) 또는 @deprecated(PEP 702) 사용 시 docstring에 폐기 안내가 없으면 감지합니다.
• missing‑return‑type (opt‑in) – 반환 주석이 없는데 Returns: 섹션에 타입이 누락된 경우 표시합니다.
• undocumented‑init‑params (opt‑in) – __init__ 메서드에 매개변수가 있지만 Args: 섹션이 없는 경우 감지합니다.

Design notes

• 역방향 검사는 위임 패턴을 고려해 권장 심각도만 사용합니다(필수는 아님).
• 옵트인 규칙은 점진적인 도입을 가능하게 합니다. 전체 설계 트레이드오프는 동반 블로그 포스트에서 논의됩니다.

Installation

pip install docvet==1.14.1

Configuration (opt‑in rules)

[tool.docvet.enrichment]
require-return-type = true
require-init-params = true

Usage

docvet check src/ --all --verbose

Docvet은 이제 시맨틱 검증을 수행합니다—단순히 “매개변수를 문서화했는가?”가 아니라 “그에 대해 말한 내용이 정확한가?”를 확인합니다. 또한 모든 규칙 카테고리에서 다중 스타일 지원을 확대했습니다.

Further reading

• PyPI
• Docs
• GitHub