Define multiline reStructuredText docstrings and item-level documentation for dataclasses, Pydantic models, and Protocols. Align agent instructions, review guidance, and development documentation.
Validation: document links, Python example syntax, docstring format, and diff checks passed. The unchanged text-only architecture documentation test passed under isolated pytest with temporary CONFIG_DIR and no application bootstrap. Normal bootstrap remains unverified because the local environment lacks moviepilot_rust; installed uv also predates the project configuration format. No product code changed.
* **Required Constraints:** Public or cross-module contracts and non-obvious business behavior require concise Chinese docstrings. Small self-evident private helpers and test scaffolding may omit them. Comments must explain the *why*, not restate the code.
* **Required Constraints:** All comment prose must be Chinese. Every docstring uses multiline triple double quotes with each delimiter on its own line and reStructuredText / Sphinx field lists such as `:param:` and `:return:`; older single-line or English file styles are not exceptions. Substantive modules, public classes, and public functions/methods require documentation. Every dataclass, Pydantic model, and Protocol must document its class, each declared field/member, and explicit methods, including private types and test scaffolding. Dataclasses use `:param:` / `:ivar:`; Pydantic fields use Chinese `Field(description=...)`; Protocol methods document each part of the calling contract. Small self-evident private helpers may omit docstrings, but non-obvious behavior must explain its rationale. Detailed formats and boundaries are defined in `08-comment-styles.md`.
* **Pattern Adherence:** Avoid generic boilerplate. If `04-design-patterns.md` defines a project-level pattern for a scenario, you are required to use it.
* **Documentation Standards:** Docstring style for any new function or module must match `08-comment-styles.md`.
* **Documentation Gate:** Public or cross-module contracts and non-obvious business behavior without useful Chinese documentation are rejected. Do not require comments that merely restate self-evident syntax.
* **Documentation Standards:** New and modified comments must follow `docs/rules/08-comment-styles.md`, the sole detailed source for comment conventions. Preserve code identifiers and tool syntax, but write explanations in Chinese. Do not rewrite runtime SQL, templates, or other strings as docstrings.
* **Documentation Gate:** Reject changes with missing required documentation, single-line docstrings, English comment prose, or undocumented dataclass / Pydantic / Protocol declarations. The rule against restating code does not waive required explanations of business meaning. Migrate existing violations within task scope; they are not accepted exceptions. Passing current static checks does not establish compliance with every comment rule.
* **Command Reliance:** Prefer commands documented in `03-commands.md`; use other necessary standard commands with explicit, scoped arguments.
* **Minimal Change Principle:** Prefer the smallest correct change. Do not perform unrelated refactors, mass renames, or formatting-only cleanup.
* **Output Language:** Summaries, validation results, and risk notes default to Chinese unless the user requests otherwise.
@@ -223,4 +223,4 @@ For the full documentation map and cross-references, refer to:
- Preserve the style of the surrounding file. When in doubt, read neighboring code first.
- Preserve the surrounding implementation style. Comments and docstrings always follow [08 — Comments and Documentation Style](08-comment-styles.md), even when neighboring code uses an older style.
- Prefer the smallest correct change. Do not introduce a new abstraction layer without a clear payoff.
- Do not add features, refactors, or abstractions beyond what the task requires.
- Do not add error handling or validation for scenarios that cannot happen. Trust internal code and framework guarantees; only validate at system boundaries (user input, external API responses).
@@ -27,6 +27,17 @@
- Do not define ad-hoc `dict` return types for API responses — define a schema class.
- Settings and deployment configuration live in `ConfigModel` / `Settings` in `app/runtime/config.py` using `pydantic-settings`.
- Use `model_validator` for cross-field validation logic.
- Every Pydantic model requires a Chinese multiline class docstring, every declared model field requires a Chinese `Field(description=...)`, and validators and explicit methods require Chinese multiline docstrings. Ordinary `#` comments and class-level `:param:` entries do not replace Schema field descriptions. Comment migration must preserve defaults, constraints, aliases, and serialization behavior.
---
## Comments and Structured Contracts
- All comment prose must be Chinese. Every docstring uses multiline triple double quotes with opening and closing delimiters on separate lines.
- Use `:param name:`, `:return:`, and `:raises ExceptionType:` for parameters, results, and exceptions, not Google-style `Args:` / `Returns:` sections.
- Every dataclass requires class and per-field documentation: `:param:` for initialization inputs, `:ivar:` for non-initialization instance attributes, and `:cvar:` for class variables. Explicitly defined methods also require documentation.
- Every Protocol requires documentation for its class, members, methods, and properties. Methods explain parameters, results, and applicable exceptions, side effects, and implementation constraints. Private types and test scaffolding are not exempt.
- Module headers, ordinary classes and functions, special Pydantic members, ordinary comments, and review requirements follow [08 — Comments and Documentation Style](08-comment-styles.md); do not introduce local formats.
---
@@ -70,14 +81,14 @@ Within each group, sort alphabetically. Do not use wildcard imports (`from modul
-`logger.exception(...)` records at ERROR level and includes the current traceback in console output by default. File and resource logs receive the formatted ERROR message through the usual routing. An explicit `exc_info` value follows standard-library logging semantics.
```python
# Correct
# 保留失败原因，便于定位外部调用问题
try:
result=self.do_work()
exceptExceptionaserr:
logger.error(f"Failed to do work: {str(err)}")
returnNone
# Wrong — swallowing silently
# 错误示例：直接吞掉异常会掩盖失败原因
try:
result=self.do_work()
except:
@@ -127,4 +138,4 @@ except:
- Do not add noisy markers like `# change starts here`, `# important`, or `# this is a fix`.
- Do not write comments that restate what the code already clearly says.
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.
This document is the sole detailed source for comment style across production code, scripts, tests, and code examples in documentation.
New and modified comments must comply even when neighboring code uses an older format or English prose.
Existing noncompliant comments remain migration work, not an alternative accepted style. Migrate within the task scope; unrelated changes do not require rewriting an entire file.
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.
- All human-authored comments, docstrings, field descriptions, and API descriptions must use Chinese. Preserve code identifiers, product names, protocol names, URLs, format labels, and tool directives such as `MediaInfo`, `HTTP`, `:param`, and `# type: ignore`.
Explanations accompanying tool directives must be Chinese. Adding a Chinese word to otherwise English prose does not satisfy this requirement.
- All docstrings use triple double quotes, with each opening and closing `"""` on its own line, even for a one-sentence description. Single-line docstrings and triple-single-quoted docstrings are prohibited. Ordinary `#` comments may occupy a single line.
- Use reStructuredText / Sphinx field lists consistently: `:param name:`, `:return:`, `:raises ExceptionType:`, `:ivar name:`, and `:cvar name:`. These are not the Google-style `Args:` / `Returns:` sections; do not mix the formats.
- Triple-quoted SQL, templates, prompts, and other runtime strings are not docstrings. Do not rewrite their content or formatting as comment maintenance. Shebangs, encoding declarations, and suppression directives are machine-readable syntax and must not be translated or broken.
- The Chinese requirement governs source comments and contract descriptions. It does not require translating English rule documents such as this one; their code examples must still comply.
---
## Content and Layout
## Docstring Format
1. Start with a short Chinese description of the purpose. Add a separate paragraph for business rules, boundaries, and behavior callers need to understand.
2. Use familiar words and short sentences that identify the object, action, and conditions. Avoid jargon piles, vague slogans, or merely repeating a class or function name.
3. Separate the summary, detailed explanation, and field list with blank lines. Do not insert blank lines between consecutive parameter or field entries.
4. Use Chinese sentence punctuation for complete sentences. Short phrase-style parameter and field descriptions do not need a final period; keep each list consistent.
5. Wrap long explanations at meaningful boundaries, indent continuation lines consistently, and respect the project line width. Do not use decorative borders, walls of asterisks, or excessive blank lines.
6. Do not duplicate existing type annotations mechanically with `:type:` / `:rtype:`. Explain business meaning instead of translating `int` into a word for integer.
7. Explain units, allowed values, default behavior, null semantics, and failure behavior where applicable. Each declared item needs useful information, not necessarily a long paragraph or an empty checklist of irrelevant concerns.
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.
| Python module with substantive content | A module docstring describing its responsibility and, where needed, boundaries and constraints |
| Public class, function, or method | A docstring describing purpose and calling contract; this includes `ChainBase`, `_ModuleBase`, and endpoint implementations |
| Private implementation | Document non-obvious business behavior, cross-module contracts, lifecycle, compatibility, and side effects; small self-evident private helpers may omit docstrings |
| Every dataclass | Document the class, every declared field, and every explicitly defined method, including private classes |
| Every Pydantic model | Document the class, every declared field, validators, and explicitly defined methods, including request, response, configuration, and internal models |
| Every Protocol | Document the class, every method, property, and declared member, including private interfaces |
| Enum / TypedDict | Document the overall purpose and every member or field |
| Constant | Explain non-obvious meaning, units, source, or the reason for its value |
| Tests | Apply the same language and format rules; small self-evident test helpers may omit docstrings |
Test scaffolding and local structures do not exempt dataclasses, Pydantic models, or Protocols from item-by-item documentation.
Unchanged inherited members retain their base documentation without duplication. Redeclarations, overrides, and semantic changes require corresponding documentation updates.
The rule against restating code does not waive required documentation: explain each item's business meaning.
## Module Headers and Class Descriptions
Place the module docstring before imports. Necessary shebangs and encoding declarations may precede it; `from __future__` follows it.
Describe the current responsibility rather than requiring author names, dates, or change history. Empty package marker files do not need added documentation; existing architecture requirements for docstring-only package roots still apply.
```python
defget_name()->str:
"""获取模块名称"""
return"Qbittorrent"
"""
下载任务的重试策略与进度结构。
本模块只表达重试规则和进度数据，不负责发起下载请求。
"""
```
### Multi-line (for methods with parameters, return values, or non-obvious behavior)
Ordinary class docstrings describe responsibility and collaboration boundaries, without `:return:`.
Document non-obvious initialization behavior in constructors and value, fallback, or side-effect behavior in properties.
A brief module header does not replace documentation of public contracts.
## Functions and Methods
Even a simple description without parameter or return semantics to expand uses the multiline format:
```python
defdownload(
self,
context:Context,
torrent:TorrentInfo,
download_dir:Path,
)->Optional[str]:
defstop(self)->None:
"""
添加下载任务到下载器
停止接收新的下载任务。
"""
```
:param context: 当前媒体上下文，包含识别结果和种子选择信息
:param torrent: 要下载的种子信息
:param download_dir: 目标保存目录
:return: 成功时返回下载任务 ID，失败时返回 None
Use `:param name:` for parameters that need explanation, `:return:` for results, and `:raises ExceptionType:` for exceptions callers must handle.
Protocol methods must explain each parameter and the return contract; ordinary functions expand the items with meaningful business semantics.
Do not document `self` or `cls` as parameters. Methods returning no data do not need a mechanical `:return: None` entry.
Use `:yields:` for generator items. Async methods describe the result after awaiting, not the coroutine object as a business result.
The following example illustrates a calling contract; the implementation is omitted:
Document caller-relevant constraints involving input mutation, persistence, transaction commits, resource acquisition and release, call ordering, concurrency, idempotency, and compatibility fallbacks.
List actual exception contracts rather than every exception an implementation detail could theoretically raise.
## Dataclasses
Every dataclass must have a multiline class docstring with a centralized description of every declared field:
- Use `:param field_name:` for initialization parameters and `InitVar` inputs.
- Use `:ivar field_name:` for instance fields excluded from initialization with `init=False`. When automatic initialization is disabled or a custom constructor exists, distinguish parameters and attributes using the actual constructor signature; do not label non-input attributes as parameters.
- Use `:cvar name:` for `ClassVar` members, not initialization parameter entries.
- Keep field descriptions in the class docstring; do not repeat them in per-field `#` comments.
- Explicit methods, properties, and `__post_init__` require multiline docstrings. Do not add implementations merely to document generated methods.
```python
classDownloadChain(ChainBase):
fromdataclassesimportdataclass,field
@dataclass
classDownloadProgress:
"""
下载处理链，负责协调搜索结果的种子选择、下载器调度和下载后处理
下载任务的进度信息。
已下载字节数从零开始，由进度更新逻辑维护。
:param total_bytes: 文件总字节数；为 0 表示尚未获取文件大小
:ivar downloaded_bytes: 已下载字节数，初始化为 0，不接受构造参数
"""
total_bytes:int
downloaded_bytes:int=field(default=0,init=False)
```
---
## Pydantic Models and Fields
## 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
Every model must have a multiline class docstring describing its purpose and cross-field constraints.
Every declared model field must use `Field(description="中文说明")`, preserving its actual requiredness, defaults, aliases, and constraints.
Neither a `#` comment nor a class-level `:param:` entry replaces a field description: they do not populate JSON Schema / OpenAPI field documentation by default.
Do not maintain a duplicate complete field list in the class docstring.
```python
# qBittorrent API 在添加种子后立即查询时可能返回空，需要短暂等待
time.sleep(0.5)
result=self.client.get_torrent(hash_id)
frompydanticimportBaseModel,Field
classSearchRequest(BaseModel):
"""
媒体搜索请求。
"""
keyword:str=Field(
...,
min_length=1,
description="搜索关键词，至少包含一个字符",
)
limit:int=Field(
default=20,
ge=1,
le=100,
description="最多返回的结果数量，默认 20 条，范围为 1 至 100 条",
)
```
Explain units, allowed values, defaults, and the difference between missing and null values where relevant; do not simply repeat the English field name.
A `description` value is a metadata string and may be single-line; it is not subject to the multiline docstring rule.
Existing `Annotated` declarations may provide the description in their `Field` metadata. Do not change declaration semantics as part of comment migration.
Document private attributes and class variables using `:ivar:` and `:cvar:` in the class docstring rather than turning them into model fields.
Computed fields require both a Chinese Schema description and a property docstring, serving API consumers and code callers respectively.
Every validator and explicitly defined method must have a multiline docstring.
Validators explain validation rules, normalization, cross-field relationships, and failure conditions instead of merely saying that they validate parameters.
Method parameters, results, and exceptions use the shared field-list format.
## Protocol Interfaces
Every interface class describes its responsibility and implementation boundary.
Use `:ivar:` for declared instance members and `:cvar:` for class variables.
Every method has its own multiline docstring explaining each parameter, its return contract, and applicable exceptions and side effects.
Properties describe their values with `:return:` in the property method docstring rather than duplicating the member description.
Make transaction ownership, resource release, concurrency limits, idempotency, and failure behavior explicit where they affect interface use.
Do not leave implementers to guess, add irrelevant empty sections, or invent new contracts merely to fill a format.
## Incorrect Examples
## Other Structures and API Documentation
- TypedDict classes document every field using `:ivar field_name:` in the class docstring, distinguishing missing keys from null values where needed.
- Enum classes describe their purpose in the class docstring and each member's business meaning in a `#` comment above its declaration.
- Non-obvious constants have preceding comments explaining units, source, or value rationale. Ordinary local variables do not each need a comment.
- API `summary` and `description` values must be Chinese. Endpoint docstrings use the shared multiline and field-list format. Summaries describe the operation; details explain permissions, limitations, and special behavior.
- SDK capabilities, compatibility paths, and lifecycle behavior require documentation of their calling contracts and necessary compatibility rationale.
## Ordinary Comments and Prohibited Patterns
Place explanatory `#` comments above the related code, not at the end of the line.
Directives that must attach to a specific line, such as `# type: ignore[...]`, `# noqa`, and `# pylint: disable=...`, may remain inline; explain their necessity in Chinese immediately above.
Do not add suppressions merely to clear diagnostics; the [quality rules](11-quality-and-security.md) still apply.
Explain external limitations, business invariants, third-party bugs, initialization order, and compatibility reasons. For example:
```python
# 获取订阅列表 ← 这只是在重述代码，不需要
subscribes=repository.list()
# 如果 result 为 None 则返回 ← 无意义
ifresultisNone:
returnNone
# change starts here ← 噪音，禁止
# fix: handle edge case ← 噪音，改成提交信息里写
# 下载器刚接受任务时可能尚未完成索引，此时空结果不代表任务不存在
result=client.get_torrent(task_id)
```
---
Prohibited patterns:
## Comment Placement
- Translating straightforward assignments, branches, or calls into comments, or adding empty statements of importance.
- Editorial markers describing where a change starts or announcing a fix; change history belongs in version control.
- Commented-out dead code.
- Single-line docstrings, English explanations, Google / NumPy sections, or appeals to an older file style to bypass these rules.
- Context-free TODO / FIXME markers. If deferral is genuinely unavoidable, explain the reason, the condition for follow-up, and a traceable issue or owner.
- 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.
Update or remove stale comments when implementation changes.
Do not promise validation, thread safety, idempotency, or exception behavior that the code does not provide.
Check the objects added or modified by the task before submission:
## Stale Comment Rule
- Chinese explanations, multiline triple double quotes, field lists, punctuation, and placement comply with this document.
- Required module, class, function, and method documentation is present.
- Every declared dataclass, Pydantic, and Protocol item has a matching explanation, with parameter and field names matching the code.
- Pydantic field descriptions reach the Schema; comment changes have not altered defaults, constraints, aliases, or serialization behavior.
- Documentation reflects actual contracts without vague placeholders, duplicate maintenance, or stale explanations.
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.
These are submission and code-review requirements. The current Pylint / Ruff configuration does not automatically enforce every comment rule.
Passing static checks does not replace this review, and updating the rules does not establish that all existing code has been migrated.
---
## 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 |
- [ ] If MCP/API behavior changed: `docs/mcp-api.md` and related skill files are updated
- [ ] If database schema changed: a new Alembic migration exists under `database/versions/`
- [ ] No secrets are included in code, logs, or committed files
- [ ]Public or cross-module contracts and non-obvious business behavior have useful Chinese documentation
- [ ]Added and modified objects comply with [08 — Comments and Documentation Style](08-comment-styles.md): Chinese explanations, multiline triple-double-quoted docstrings, shared parameter/return field lists, and complete required module, class, function, and method documentation
- [ ] Every affected dataclass, Pydantic, and Protocol declaration has accurate documentation; Pydantic field descriptions reach the Schema, and comment migration has not changed model behavior
- [ ] Older file styles and passing static checks do not replace comment review; existing migration work does not justify new violations
@@ -50,7 +50,7 @@ This repository maintains a structured documentation library covering the full d
* **08 Comments and Documentation Style**
* File: `08-comment-styles.md`
* Scope: Chinese docstring requirements, inline comment rules, and prohibited comment anti-patterns.
* Scope: Project-wide Chinese comments, multiline docstrings, reStructuredText / Sphinx field lists, module/function documentation, item-by-item dataclass / Pydantic / Protocol documentation, and review requirements. This is the sole detailed source for comment conventions.
### Section IV: Quality and Governance
@@ -74,6 +74,7 @@ Developers actively writing or modifying features should follow this reading pat
2.**06 Code Standards** — ensures linting and logic compliance.
3.**04 Design Patterns** — identifies the correct structural approach.
4.**03 Commands** — required for local execution and validation.
5.**08 Comments and Documentation Style** — mandatory conventions for new and modified comments; older single-line or English styles are not exceptions.
### System Architects and Reviewers
@@ -104,4 +105,4 @@ Those managing the application lifecycle post-development:
---
*Last Updated: 2026-08-24*
*Last Updated: 2026-10-17*
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
DDSRem