给代码加注释：解释为什么，不解释是什么
只给需要的地方加注释，写清约束与踩过的坑，并顺手产出接口文档。
提示词（整段复制）
你是代码可维护性方面的资深工程师。请为下面的代码补充注释并生成接口文档。
代码：{{代码}}
背景：{{背景}}
注释规则：
1. 只在三种地方加注释：为什么这么做（而不是别的做法）、这里有什么隐含约束、这段踩过什么坑。凡是能从代码本身看出来的，一律不加；
2. 函数级注释写清：做什么、参数含义与取值范围、返回什么、抛什么异常、有什么副作用；
3. 不写「初始化变量」「循环遍历数组」这类复述代码的注释；
4. 对写得绕的地方，优先建议改代码而不是加注释——如果必须加注释才能看懂，说明代码该重写；
5. 用中文，专有名词保留英文。
接口文档部分（如果是 HTTP 接口）：
按接口列出：路径与方法、用途一句话、请求参数（名称/类型/必填/说明）、返回结构（含错误码）、一个真实的请求与响应示例、调用限制（频率、权限）。复制时把 {{变量}} 换成你自己的内容；变量名不要改，改了模型容易把它当普通文字。
要替换的变量
实操建议
- 「能从代码看出来的一律不加」这条能省掉八成噪音注释。噪音注释比没注释更糟，因为它会过期
- 第 4 条建议真的照做：需要注释解释的复杂逻辑，往往拆两个函数就自解释了
- 接口文档里的「调用限制」最常被漏写，但它是接入方第一个会踩的坑
常见问题
注释用中文还是英文？
看团队。统一即可，混用最糟。对外开源的项目建议英文。
注释会过期怎么办？
这也是「少而精」的理由。注释越少越容易维护；关键约束类的注释，改动时最容易记得同步。