TRAE-AI编程
AI 写注释的效果，八成取决于提示词里写没写清边界。本文给出可直接套用的三种提示词写法：指定角色与文件类型、给出上下文与约束、附上示例代码片段，并配一组「差提示词→好提示词」的对照样例。核心结论是，提示词里必须写清「注释要写到什么粒度、不写什么」，只说「帮我加注释」得到的结果往往要么是复述代码，要么是满屏废话。下面每段都解释为什么这么写，并附常见失败与修复方向。先确认代码语言和注释风格，再决定用哪种写法。
一、先看结论：提示词里必须写清三件事
下面这张表给出提示词的三要素，缺一件结果就会偏。写注释这件事看起来简单，难点恰恰在边界：说清楚「要写什么」容易，说清楚「不写什么」才决定注释质量。
| 要素 | 写什么 | 缺失后的结果 |
|---|---|---|
| 定位 | 角色、语言、文件类型 | AI 用通用口吻回复，不贴合项目 |
| 边界 | 注释写到什么粒度、不写什么 | 要么复述代码，要么满屏无信息量注释 |
| 示例 | 一行目标风格的注释样例 | 风格不统一，同一文件里五种写法 |
这个结构的依据是：AI 无法知道你的项目偏好，只能从提示词里推断。把「不写什么」明确写进去，比多写两百字解释都有效。想在线对照不同提示词的回复差异，可用 在线代码实例 验证实际结果。
二、环境确认与最小示例
先用一段常见的 Python 函数做样本，再分别用差提示词和好提示词去写注释，直接对比结果差别。以下为预期结果说明，未在本机执行，按主流 AI 助手响应规律推断。
# 待注释的样本函数：计算订单折扣后的实付金额
def calc_pay(order_amount, discount, is_vip):
if is_vip:
discount = discount * 2
if discount > 0.5:
discount = 0.5
return order_amount * (1 - discount)把下面两段提示词分别发给 AI，得到的注释差别很大。差别不在于谁词多，而在于有没有给出边界和示例。Python 版本差异对注释内容没有影响，注释本身也不参与运行，所以这部分结论可以通用。
# 差提示词：只有动作，没有边界
帮我给这段代码加上注释。# 好提示词：定位 + 边界 + 示例，三要素齐全
你是 Python 技术文档的写作者。请给下面的函数写行内注释：
1. 只解释「为什么这么写」，不逐行复述代码在做什么；
2. 不写 def、if、return 这类语法本身；
3. 每个分支最多一行，控制在 40 字以内；
4. 参考这种风格：# VIP 折扣翻倍，但封顶 50%，避免超长折扣亏损
函数是：
def calc_pay(order_amount, discount, is_vip):
对照是不是很直观：差提示词得到的注释往往是 计算折扣 、判断是否为VIP 这类复述，好提示词得到的注释会说明折扣翻倍和封顶的原因。这个差距不是模型能力问题，而是边界没给。想把注释工作交给 AI 又不想返工，可以把上面三要素固化成模板存进项目提示目录，再用 Python 教程 校准语法表述。代码注释最终以三个月后的自己能不能看懂为准，而不是以 AI 回复了多少字为准。
三、写法一：先给角色和文件类型
第一要素是定位。告诉 AI 你的角色和文件类型，它才会用对应的口吻输出。适用于新项目第一次生成注释，或者要统一一个文件的全部注释。
# 提示词：指定角色与文件类型
你是负责维护这个 Django 视图文件的工程师，请为下面这段代码写注释。
注释语言用中文，面向刚接手这个项目的同事。这种写法的判定标准是：回复里不该出现与 Django 无关的建议。如果 AI 开始讲别的框架，说明定位没生效，需要把文件类型写得更具体，比如补上「这是 Django 4 的 CBV 视图」。
四、写法二：用「不要做什么」划边界
第二要素是边界，也是最容易被忽略的一层。只说「请写注释」时，AI 默认会逐行翻译代码；明确写出不写什么，才能挤出真正有信息的注释。
# 提示词：用否定句划出边界
请给下面这段代码写注释，注意：
不要复述函数名和变量名已经表达的信息；
不要写「这里判断是否为VIP」这类解释语法的话；
只写 business rule、边界条件和容易踩坑的地方。
判定标准很具体：注释里不该出现 如果、判断、返回 这些复述性词汇命中率高。这里还有一层取舍值得说清：函数签名本身已经表达的参数含义，不必在行内再写一遍；真正会变的是业务规则，比如为什么封顶 50%、为什么 VIP 折扣要翻倍，这些从代码里看不出来的原因才是注释该占的位置。判断标准可以一句话概括——删掉这行注释，三个月后的你还能看出这里为什么要特殊处理吗？看不出就写，看得出就别写。命中了就说明边界没写清，补上否定句重试即可，不必反复解释需求。这个技巧对长文件尤其有效，能省掉大量无效注释。
五、写法三：附一行风格示例
第三要素是示例。给一行符合目标风格的注释，比描述十种要求都管用，也最能让同一批注释风格统一。
# 提示词：附一行风格示例
请按下面这行注释的风格，为剩余代码写注释：
# 封顶 50%：超过这个比例会导致实付低于成本价
风格要求：一句话说清原因，不超过 40 字，不用感叹号。示例法的优势是结果可预测。修复方向的判断标准是：看生成的第一行注释能不能照抄进第二个函数还说得通，说得通就说明风格统一了。想在线验证同一提示词在不同代码上的表现，可以配合 Python 速查手册 一起用。
总结
让 AI 写注释，提示词里必须写清三件事：定位，说清角色和文件类型；边界，用否定句划出「不写什么」；示例，附一行目标风格注释。三件事里边界最有效，只说「帮我加注释」得到的往往是复述代码，明确写出不要复述语法之后，注释的信息量会有明显差别。使用时先确认代码语言和注释风格，再用定位加边界加示例的顺序组织提示词，最后用「有没有复述代码」这一条标准做验收。
延伸学习
想在编程狮系统学 AI 辅助编程，可以顺着下面三篇深入：
常见问题
Q：为什么我写的提示词得到的注释像在翻译代码？
A：因为你没有给出「不写什么」。AI 不知道你的项目偏好，默认会逐行说明。补上否定句，比如「不要解释 if、for 这类语法本身」，比多描述需求有效得多。
Q：注释写多少合适？
A：以「三个月后的自己能不能看懂」为标准。解释业务规则、边界条件、易踩坑处的注释值得留，复述函数名的注释可以删。宁可少而准，不要多而空。
Q：不同文件的注释风格不统一怎么办？
A：先给一行风格示例，再让 AI 按这个风格处理剩余文件。示例法的可预测性最强，比用文字描述五种要求更有效。生成后抽查两个文件，风格对得上就批量采用。
Q：注释和文档冲突了以哪个为准？
A：以文档为准，注释只写「为什么」。当代码行为与文档描述不一致时，优先改代码或注释，不要让两处各说一套；这类矛盾后期排查成本很高。
