体面编码之代码注释评论

避免无意义的注释评论，不添加任何价值。如果通过阅读代码可以清楚地看到某些内容，则评论只会增加噪音。

考虑是否可以改进代码，以便不再需要注释。通过改进命名，重构（例如，提取函数）或引入解释变量，通常可以解释解释代码正在做什么以及有时为什么的注释。

考虑一个单元测试是否会更好的沟通。构造良好和命名的单元测试可以解释代码背后的原因，以及在不同情况下演示和验证其行为。

解释从代码中不清楚的推理。预计未来的维护者可能会对代码感到困惑。示例包括边缘案例处理，必须解决的约束以及性能优化。

提请注意令人惊讶的“陷阱”。如果某些事情不直观或者让你感到困惑，可能值得注意帮助他人。示例包括看似不合逻辑的业务“逻辑”，以及令人惊讶的库代码行为。

解释特定“魔术值”的选择。这些包括框架/服务器设置，超时，限制，批/池大小，优先级，缓存配置和排序。我们熟悉从代码中将这些值提取到常量或配置中，但是经常忽略选择实际值的原因。在某些情况下，这是在花费大量精力进行负载测试等活动以便选择适当的值之后。记录这些内容可以更有信心地进行未来的更改。

突出显示错误解决方法，链接到问题报告。这样可以在以后修复基础错误（例如库中）时轻松识别和删除它们。查看 错误修复 。

记录代码的远程和断开部分之间的关​​系。通过代码无法显示这些内容是非常罕见的。它们通常是某种方式的东西，因为远处的东西（甚至可能在下游系统中）是某种方式 - 例如依赖性或匹配行为。改变一个可以以令人惊讶的方式打破另一个，或者引入用户体验的不一致。

写得清楚，简洁，明确。遵循这些原则的评论更快更容易理解，有助于避免误解或混淆。写作过程通常可以触发问题的想法或解决方案，就像仅向某人解释问题可以帮助您提出解决方案一样。重构不仅适用于代码; 写完评论后，阅读并考虑是否可以改进。

确保注释与当前版本的代码保持同步和正确。过时或不再适用的评论可能会引起混淆。

遵循项目管理TODO评论的策略。在代码中积累这些评论通常表明技术债务和必要工作的累积。这些任务对于项目功能/错误工作跟踪仍然是不可见的，使它们处于被忽视和遗忘的危险之中 - 带来各种后果。其中一种策略是要求所有TODO在合并拉取请求之前引用问题跟踪器票证。