Code Comments · 代码注释指南

帮助团队编写真正有价值的代码注释——解释"为什么"，而不是"是什么"。

触发关键词: 写注释、加注释、注释规范、注释审查、comment、docstring、JSDoc、注释怎么写

核心原则

解释 Why，不解释 What。

注释的唯一价值是传达代码本身无法传达的信息：设计决策、业务背景、非直觉行为、已踩过的坑。

注释前先问自己：
  ✅ 这解释了为什么代码这样写吗？
  ✅ 这段背景知识读者不看注释会知道吗？
  ❌ 这只是把代码翻译成自然语言吗？→ 删掉它