体面编码之代码注释评论

18-12-31 banq
              

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

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

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

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

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

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

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

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

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

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

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