85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
|
---
|
|||
|
|
name: "py-zh-commenter"
|
|||
|
|
description: "为 Python 代码补充清晰的中文注释与必要 docstring。用户要求“加中文注释/解释这段代码/补齐注释/可读性提升”时调用。"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Python 中文注释助手（py-zh-commenter）
|
|||
|
|
|
|||
|
|
## 目标
|
|||
|
|
|
|||
|
|
在**不改变代码行为**的前提下，为 Python 代码补充高质量的中文注释与必要的 docstring，提升可读性与可维护性。
|
|||
|
|
|
|||
|
|
## 何时调用
|
|||
|
|
|
|||
|
|
当用户提出以下需求时调用：
|
|||
|
|
- “给这段 Python 代码加中文注释/补齐注释”
|
|||
|
|
- “解释代码在做什么，希望在源码里体现”
|
|||
|
|
- “帮我把关键逻辑注释清楚/写 docstring”
|
|||
|
|
|
|||
|
|
不适用于：
|
|||
|
|
- 纯代码审查（请用 code-reviewer / pr-reviewer）
|
|||
|
|
- 重构/改逻辑（除非用户明确要求）
|
|||
|
|
|
|||
|
|
## 输出原则（必须遵守）
|
|||
|
|
|
|||
|
|
1. **不改逻辑**：仅添加注释/docstring 与必要的类型提示（仅当非常明确且不影响行为）。
|
|||
|
|
2. **少而精**：不写“显而易见”的注释；只解释“为什么/边界/约束/不变量/副作用/复杂算法/业务含义”。
|
|||
|
|
3. **就近放置**：
|
|||
|
|
- 模块：文件头 docstring（可选，描述模块职责）
|
|||
|
|
- 类/函数：docstring（参数/返回/异常/副作用/线程安全/性能）
|
|||
|
|
- 复杂分支/循环：行内注释说明意图与约束
|
|||
|
|
4. **风格一致**：遵循项目现有格式（注释语气、标点、缩进、是否偏好 docstring）。
|
|||
|
|
5. **安全合规**：不在注释中写入密钥、口令、内网地址等敏感信息；不把用户数据或隐私写进注释。
|
|||
|
|
6. **避免噪音**：不要对每行都加注释；避免把代码翻译成中文。
|
|||
|
|
|
|||
|
|
## 注释内容清单（优先级从高到低）
|
|||
|
|
|
|||
|
|
- 业务含义：字段/表/状态机/权限点的语义
|
|||
|
|
- 不变量：必须满足的条件（例如“role_id 必须存在且启用”）
|
|||
|
|
- 边界情况：空值/异常路径/并发/重试/超时
|
|||
|
|
- 副作用：数据库写入、网络请求、文件读写、全局状态变更
|
|||
|
|
- 性能：复杂度、批处理、索引依赖、潜在慢点
|
|||
|
|
- 安全：鉴权、权限校验点、数据校验原因
|
|||
|
|
|
|||
|
|
## 注释模板（可直接复用）
|
|||
|
|
|
|||
|
|
### 函数 docstring（推荐）
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def foo(x: int) -> int:
|
|||
|
|
\"\"\"一句话说明做什么。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
x: 参数含义（业务语义/单位/范围）。
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
返回值含义（单位/范围/是否可能为空）。
|
|||
|
|
|
|||
|
|
Raises:
|
|||
|
|
ValueError: 触发条件说明。
|
|||
|
|
\"\"\"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 复杂分支注释（示例）
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 这里做 X 的原因：……
|
|||
|
|
# 约束：……（例如必须在事务内/必须先校验权限）
|
|||
|
|
if cond:
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 执行步骤（给模型的工作流）
|
|||
|
|
|
|||
|
|
1. 先快速阅读：识别模块职责、关键数据结构、外部依赖（DB/HTTP/文件/线程/协程）。
|
|||
|
|
2. 找“复杂点”：多层嵌套、隐藏副作用、异常处理、权限判断、数据转换。
|
|||
|
|
3. 优先写 docstring：为对外接口（路由函数/服务方法/工具函数）补齐输入输出语义。
|
|||
|
|
4. 补关键行注释：只在需要解释“意图/原因/约束”的地方写。
|
|||
|
|
5. 自检：确保不引入代码变更、不新增导入导致 lint/test 变化。
|
|||
|
|
|
|||
|
|
## 交付格式
|
|||
|
|
|
|||
|
|
- 如果是仓库内改动：直接在对应 `.py` 文件中增加注释/docstring。
|
|||
|
|
- 如果用户只要解释：给出“建议应写在源码中的注释内容”，并可选附带 patch。
|
|||
|
|
|