code-comments-vp

Code Comments VP

Goal

Write maintainable comments that explain responsibility, execution flow, boundaries, side effects, fallback behavior, and design reasons.

Golden rule:

优先解释“为什么这样写”和“这段代码在链路中承担什么责任”，少解释“这行代码语法上做了什么”。

Mode Selection

Choose one mode before editing:

• coarse: Add or improve comments for a file, module, class, or function. This is the default.
• fine: Add detailed block comments because the user asks for细粒度/逐段/逐行 comments, or the code contains complex branching, async/concurrency, cache, fallback, state mutation, external calls, security checks, performance-sensitive logic, or business rule priority.
• review: Review whether comments are sufficient. Lead with findings and suggestions before changing anything.
• rewrite: Existing comments are inaccurate, noisy, inconsistent, or too shallow. Preserve correct meaning and rewrite in this style.
• style-transfer: The user points to an example file. First extract the comment style, then apply it to the target code.

Default Style

Default to coarse-grained comments. Prefer module docstrings, class docstrings, and function docstrings before inline comments.

Use Chinese comments by default when the user uses Chinese or the surrounding project comments are Chinese.

Use these section labels when useful:

• 执行流程：
• 参数：
• 返回：
• Yields:
• 异常：
• 说明：
• 字段说明：
• 规则说明：
• 兜底策略：

Read references/comment-patterns.md when adding or rewriting more than one docstring, when the user asks for a reusable style, or when fallback/import-level comments are involved.

Coarse-Grained Template

Use this module docstring for most Python files:

"""模块职责一句话。

说明这个文件处在哪一层、接收什么输入、调用哪些下游能力、产出什么结果。
如果是 API / service / pipeline / adapter / config 文件，说明它的边界职责。
"""

Use this function docstring for important functions:

def some_function(...):
    """一句话说明这个函数在业务链路中的作用。

    执行流程：
    1. ...
    2. ...
    3. ...

    参数：
        xxx: 来源、含义、影响范围。

    返回：
        xxx: 返回内容和关键字段含义。

    异常：
        xxx: 什么时候抛出，调用方应如何理解。
    """