副标题 / 摘要#注释不是越多越好，而是要写“为什么”和“约束”。本文给出注释的使用原则与实践建议。
目标读者#需要维护多人协作代码库的工程师负责代码评审的开发者想提升可读性的团队背景 / 动机#很多注释只是复述代码本身，反而会过时并误导。好的注释应该解释“意图、约束和风险”。
核心概念#注释的价值：解释意图与约束注释的风险：过时、与代码不一致自解释代码：清晰命名与结构实践指南 / 步骤#优先让代码自解释用注释说明“为什么”记录边界条件与陷阱避免重复代码语义注释必须随代码更新可运行示例## 好注释：说明为什么要这么做
def get_user(user_id, cache):
# 避免热 key 反复击穿数据库
if user_id in cache:
return cache[user_id]
return None
解释与原理#注释的核心价值是“传递上下文”。代码告诉你“做了什么”，注释告诉你“为什么这样做”。
常见问题与注意事项#注释越少越好吗？不一定，关键是信息密度。
什么时候必须写注释？边界条件、性能技巧、安全逻辑。
TODO 注释合理吗？可以，但必须有可追踪的任务编号。
最佳实践与建议#写“意图”和“约束”避免“翻译式注释”注释更新纳入评审小结 / 结论#注释是沟通工具，不是装饰。写对注释能显著降低维护成本。
参考与延伸阅读#Clean CodeThe Pragmatic Programmer元信息#阅读时长：6~8 分钟标签：注释、代码规范、可维护性SEO 关键词：代码注释, 可维护性元描述：注释什么时候有用，以及如何正确编写。行动号召（CTA）#在一次代码评审中标注“为什么”的注释，而不是“做了什么”。