怎样写代码评论

概要

通常来说当你代码评审代码时保持礼貌和尊重很重要，这也能使开发人员更加清晰，得到更多帮助。这样是为了保证你的代码评论仅仅针对的是code而不是针对开发人员。你不必一直这么去做，但是当你的评论会让开发人员生气或者产生争执时有必要这么去做。比如：

反例: "你为什么会在这里使用线程，这样做难道会有任何好处？"

正例: "我并没有发现这个并发模块给程序带来了多少帮助，并且还增加了程序的复杂性，因此我认为这段代码最好是用单线程而不是多线程。

从上面“好”的例子当中你能发现，这样有助于开发人员理解为什么你写了这些评注。你不一定非得包含这些信息在你的评注里面，但是适当的多解释你的意图或者多给出一些提升代码质量的建议都是非常好的实践。

通常来说修复CL是开发人员的职责而不是评审人员的。你不需要向开发人员提供详细的解决方案或者代码。

但是这并不意味着评审员就不应该提供帮助。你需要在指出问题和提供直接指导之间找到平衡。指出问题并且帮助开发人员决策能够帮助开发人员学同事让代码评审变得更加简单。这样也能产生更好的方案，因为开发人员比评审者更加了解代码。

尽管这样，有时候直接给出指导，建议甚至是代码更有帮助。代码评审的主要目的是尽可能得到最好的CL。其次是提高开发人员的技能这样就能减少以后评审的次数。

与其要求让开发人员解释一段你看不懂的代码，其实更应该做的是让他们重写代码，让代码更清晰。当一段代码不是太过于复杂的时候通过加一些注释偶尔也是一种不错的做法。

**解释仅仅是写在代码评审工具里的，不利于将来的代码阅读者。**只有极少数情况是可行的，比如你对你评审的需求不太熟悉，但是开发人员解释的是大多数人都知道的。

Last updated 2 years ago