代码注释规范与 docstring 生成提示词（Google 风格 / JSDoc / Javadoc，只写「为什么」）
代码要交接、要开源、或者自己过一个月就看不懂时用：在不改动任何逻辑的前提下，补齐函数和类的文档注释、给关键逻辑加「为什么这样写」的注释，并删掉过时和废话注释。
通用大模型 对话模型通用
【角色】你是一名对注释很挑剔的资深工程师。你的信条：代码说明「做什么」，注释说明「为什么」；一条和代码不一致的注释比没有注释更糟。 【输入】 - 语言：[语言] - 文档注释风格：[Google/NumPy/JSDoc/TSDoc/Javadoc/Go doc] - 注释语言：[中文/英文] - 读者：[接手的同事/开源用户/未来的自己] - 代码： [粘贴代码] 【要做的事】 1. 为每个对外的函数、方法、类补全文档注释：一句话概括 → 必要时补一段说明 → 参数（含单位、取值范围、是否可为空）→ 返回值 → 可能抛出的异常或返回的错误 → 一个最小用法示例（适合放示例的才放）。 2. 在不直观的地方加行内注释，只解释意图、业务规则、绕过的坑、性能或兼容性考虑，例如「这里用整数分而不是浮点元，避免舍入误差」。 3. 删除或改写：复述代码的注释（如「i 加 1」）、与代码不符的注释、被注释掉的大段旧代码（改为建议删除并说明可以在版本历史中找回）。 4. 遇到看起来像 bug、或意图不明的代码，不要改，在旁边加 TODO 或 FIXME 注释写明疑点，并汇总到最后的清单里。 【硬性约束】 - 一个字符的逻辑都不能改：不改名、不调整顺序、不改格式化风格；只动注释。 - 遵守所选风格的格式细节，例如 Go 的文档注释以被注释的标识符名称开头，JSDoc 用 @param 与 @returns。 - 从代码里推断不出的信息（如参数的业务含义）用「待确认」标注，不要编。 - 注释长度克制：简单函数一行概括即可，不要为了「覆盖率」写空话。 【输出】 1. 完整的加注释后代码（一个代码块）； 2. 改动摘要：新增了哪些文档注释、删除了哪些注释及原因； 3. 疑点清单：位置 | 疑点 | 建议确认的问题。
高亮处换成你自己的内容：[语言]、[中文/英文]、[接手的同事/开源用户/未来的自己]、[粘贴代码]
ChatGPT Plus 充值
已被复制 0 次
使用说明
怎么填变量：[文档注释风格] 跟随项目已有约定；Python 项目要用 Sphinx 生成文档时，Google 和 NumPy 风格需要开启 sphinx.ext.napoleon 扩展才能正确解析。[读者] 是开源用户时，注释会更偏使用说明；是接手同事时，会更偏业务背景和历史原因。
常见坑：AI 加注释时偶尔会「顺手」改代码（重命名变量、调整格式）。验证方法很简单：把输出代码和原代码去掉注释后做 diff，应当完全一致。另外，业务背景是 AI 看不出来的，比如「为什么超时设成 8 秒」，这类注释要你自己补上原因。
追问技巧：对疑点清单逐条回答后，说「根据我的回答更新注释并删除对应的 TODO」；也可以追问「哪些函数如果改个名字就不需要注释了」，把注释压力转回到命名上。
示例输出
示例，仅供参考（Python，Google 风格）
python
def split_amount(total_cents: int, parts: int) -> list[int]:
"""把金额平均拆成若干份，除不尽的余数依次分给前几份。
全程用整数「分」计算，保证拆分后各份之和严格等于总额。
Args:
total_cents: 总金额，单位为分，必须大于等于 0。
parts: 份数，必须大于等于 1。
Returns:
长度为 parts 的列表，各项之和等于 total_cents。
Raises:
ValueError: parts 小于 1 或 total_cents 为负数时。
Example:
>>> split_amount(100, 3)
[34, 33, 33]
"""
if parts < 1 or total_cents < 0:
raise ValueError("parts 必须 >= 1 且 total_cents 不能为负")
base, remainder = divmod(total_cents, parts)
return [base + 1 if i < remainder else base for i in range(parts)]同款作品
用这条提示词做出来的作品；原作者会因此获得积分
还没有同款，来做第一个。
0 条评论
还没有评论，来抢沙发～