为提高代码可读性与可维护性，所有公开接口、关键逻辑及复杂算法均需携带符合规范的注释。推荐利用工具自动生成文档，确保格式统一、内容完整。
1. 基本要求
- 公开类、接口、方法、枚举、常量必须添加文档注释（如 Java 的
/* ... /，Python 的 docstring）。 - 注释应简洁描述“做什么”而非“怎么做”，避免无意义的废话（如
// 设置名字优于// 这是设置名字的方法）。 - 与代码同步更新，修改逻辑时必须同步修改对应注释。
2. 标准标签
使用标准的文档标签，至少包含以下元素（以 Java 为例）：
/**
* 计算订单折后总价。
*
* @param orderId 订单ID，不能为空
* @param discount 折扣率，取值范围 (0,1]
* @return 折后金额，保留两位小数
* @throws IllegalArgumentException 折扣率非法时抛出
*/
public BigDecimal calculateFinalPrice(String orderId, double discount) {
// ...
}@param：参数说明，包含约束条件（是否可空、取值范围等）。@return：返回值说明，无返回值时省略。@throws/@exception：明确列出可能抛出的受检或非受检异常及触发条件。@see、@since、@deprecated等标签按需使用。
3. 自动生成与检查
- 生成工具：项目统一配置文档生成器（如 Java 的 Javadoc、Python 的 Sphinx、TypeScript 的 TypeDoc），通过 Maven/Gradle 或脚本自动构建 API 文档。
- 静态检查：将注释缺失或格式不规范作为 CI 流水线的一个检查项（如 Checkstyle、ESLint 的
valid-jsdoc规则），不合规则阻止合并。 - 模板提示：IDE 中配置 Live Template，输入
/**按回车自动补全标签骨架，减少手工输入，降低遗漏风险。
4. 包与模块注释
- 每个包或模块目录下放置
package-info.java或init.py等文件，集中描述包职责、设计意图和主要依赖，便于新人快速理解系统结构。
以上规范兼顾人工阅读与工具提取，在团队协作中可显著降低沟通成本，提升接口使用效率。