# 注释（Comment）

### 缩写：无

### 简述

源码中不被当作可执行逻辑的说明性文本，用于记录意图、约束、背景与警告。注释服务读者与未来维护者；过时注释比没有注释更危险。文档注释（如与工具链集成的格式）还可生成 API 文档，但仍须与真实行为同步。

### 使用场景

解释非显然的「为什么」、标记临时方案与风险、生成文档、许可证头。

### 实践与应用

```text
// 写「为什么」与约束
// 勿复述代码字面意思
// 过时注释比没有更糟
```
### 注意事项

• 复述代码字面意思的注释增加噪音。
• 被注释掉的大段死代码应用版本历史替代。
• 注释中的过期假设会导致错误修改。

### 关联术语

• 源代码：注释依附的文本
• 可读性：命名与结构优先，注释补意图
• 文档注释：可生成 API 说明的约定格式