08 — Comments and Documentation Style

Documentation Gate

Public and cross-module contracts, structured business models, lifecycle behavior, compatibility paths, and non-obvious side effects require useful Chinese documentation. Small self-evident private helpers, temporary test scaffolding, and local structures whose contract is already clear may omit formal docstrings.

Names without a leading _ are review candidates, not an automatic documentation requirement. Apply the gate to the behavior and contract actually exposed. Methods on ChainBase subclasses, _ModuleBase subclasses, Pydantic schema classes, and endpoint functions normally cross a meaningful boundary and should be documented unless the surrounding contract already makes their role self-evident.

Docstring Format

Short, label-style docstrings, field descriptions, and single-line comments should follow the surrounding code style and must not gain a period mechanically. Complete sentences that explain non-obvious behavior should use normal Chinese punctuation.

Single-line (for simple, obvious descriptions)

def get_name() -> str:
    """获取模块名称"""
    return "Qbittorrent"

Multi-line (for methods with parameters, return values, or non-obvious behavior)

def download(
    self,
    context: Context,
    torrent: TorrentInfo,
    download_dir: Path,
) -> Optional[str]:
    """
    添加下载任务到下载器

    :param context: 当前媒体上下文，包含识别结果和种子选择信息
    :param torrent: 要下载的种子信息
    :param download_dir: 目标保存目录
    :return: 成功时返回下载任务 ID，失败时返回 None
    """
    ...

Class docstrings

class DownloadChain(ChainBase):
    """
    下载处理链，负责协调搜索结果的种子选择、下载器调度和下载后处理
    """

Docstring Language Rule

Default: Chinese.
Exception: If the surrounding file is entirely and consistently in English, match the local style.
Do not mix languages within a single docstring. Pick one and stay consistent for the whole file.

Inline Comments

Only add an inline or block comment when the WHY is non-obvious. Good reasons to add a comment:

A hidden external constraint (e.g., "this API returns stale data for up to 60 seconds after update")
A subtle invariant the code must maintain
A workaround for a specific third-party bug
Call ordering or initialization requirements that are not apparent from the code
Compatibility reasons with a specific client version or protocol

Do not add a comment when:

The code already explains itself through well-named identifiers
The comment would just restate what the code does in words
The logic is straightforward branching or assignment

Correct Examples

# qBittorrent API 在添加种子后立即查询时可能返回空，需要短暂等待
time.sleep(0.5)
result = self.client.get_torrent(hash_id)

# 此处必须先检查 module 是否已初始化，否则多线程并发调用时 get_instances() 可能返回空列表
if not self._initialized:
    self.init_module()

Incorrect Examples

# 获取订阅列表  ← 这只是在重述代码，不需要
subscribes = SubscribeOper().list()

# 如果 result 为 None 则返回  ← 无意义
if result is None:
    return None

# change starts here  ← 噪音，禁止
# fix: handle edge case  ← 噪音，改成提交信息里写

Comment Placement

Place block comments above the code they describe, not on the same line.
Use same-line end-of-line comments only for very short clarifications (e.g., unit of a constant).
For long explanations, prefer a block comment above the code rather than a multiline end-of-line comment.

# 优先使用已有的下载目录映射，避免重复计算路径
effective_dir = self._resolve_download_dir(torrent) or download_dir

Stale Comment Rule

When modifying code, update or remove any comment that no longer accurately describes the implementation. A stale comment is worse than no comment — it actively misleads future readers.

Prohibited Patterns

Pattern	Why
`# change starts here` / `# change ends here`	Editorial noise; belongs in git history, not source
`# TODO` without context or assignee	Accepted only when the deferral is genuinely unavoidable and the reason is documented
`# FIXME` left in submitted code	Fix it now or document exactly why it cannot be fixed
`# this is important`	Every line of code is important; this adds nothing
Commented-out dead code	Delete it; git history preserves it
New contract documentation in English inside an otherwise Chinese file	Breaks the repository's default documentation language and local consistency

Last Updated: 2026-08-13

4.8 KiB Raw Permalink Blame History Unescape Escape