在代码审查中注释的最佳方法是什么？

每当我们一个人签入某项内容时，我的团队就开始使用坩埚/鱼眼镜头来发起代码审查。我们只有3个人，我们每个人都被鼓励审查代码并在我们认为合适的地方留下评论。

我的问题是，如何最好地在遇到问题的代码行上留下评论？我想表达自己的观点而又不显得刻板。

我不想看起来像是骑着马，说：“ 我一直在做这种事…… 而且我也不想看起来像是我在试图变得权威，说些类似的话。 “ 这应该以这种方式完成... ”但是我仍然需要弄清楚他们在做什么并不是很好。

澄清一下： 对于我应该评论的内容，这确实是一个很好的资源：代码审查是主观的还是客观的（可量化的）？，但我正在寻找如何对此发表评论。

好吧，我倾向于在几个一般领域中发表评论，每种类型的处理方式可能有所不同。

必需的更改。这些更改是我指出代码不符合功能要求或无法正常工作，必须在将其投入生产之前进行修复的更改。在这些评论中，我倾向于很简单。要求说...，这不是这样做的。否则，如果传入的值为null（特别是当您知道这种情况将基于传入的数据发生）时，这将失败。

然后有“这项工作，但这是完成此任务的更好方法”的评论。您必须在这些方面更加温柔，并做更多的销售推销。我可能会说我会这样做，因为它的性能可能更好（我通常会回顾性能非常重要的SQL代码）。我可能会添加一些有关为什么它是更好选择的详细信息，就像我在回答Stack Overflow上的问题时所做的那样。我可能会指出，不需要为此特定代码进行更改，而是要考虑将来的编码更改。基本上，通过这些类型的评论，我教育的是经验不足的人，哪些可能会更好。

然后是“这有效，但我们以这种方式做事”的注释。这些可能也将是必需的更改。这些内容包括对公司标准或我们希望它们使用的体系结构的评论。我会参考标准或体系结构文档，并告诉他们修复该标准。注释将是直接但中立的，因此会丢失，或者变量名不符合我们的命名标准或类似内容。例如，我们用于SSIS包的体系结构要求该包使用我们的元数据数据库来存储有关该包的特定信息，并且需要特定的日志记录。该程序包可以在没有这些问题的情况下工作，但是出于公司原因，它们是必需的（例如，我们需要报告导入成功率或分析我们收到的错误的类型。）

您不想在代码审查注释中做的一件事就是亲自攻击某人。如果您发现他们做得很好，并指出这是件好事，这也可能会有所帮助。有时我会从代码审查中学到一些新知识，如果我这样做了，我会告诉对方。

如果代码遵循您的编码标准，但是您会采用其他方式，则必须问自己是否做错了。

如果不是...那不是您将如何做，而您就不能离开它，请尝试问“为什么用这种方式而不是那样？” 然后，您将使他们有资格证明他们为什么如此做，而不必说“我会这样做，您也应该……”

您可能还会在此过程中学到一些东西。

我想表达自己的观点而又不显得刻板。

不要将简洁与打磨混为一谈。当出现问题时，请以解决问题的人可以理解的方式记录下来。坚持事实，不要写文章。以机智：

• 当愚蠢程度在snorgatz因子的5格之内时，这将导致frobnitz发生故障。

• 这样做的惯例是使用刚初始化的Squidge调用fazzatz（）。使它成为一种方法，使其始终以相同的方式发生并且不会重复。

  我也不想让自己看起来像权威，而是说“应该以这种方式完成...”之类的事情，但是我仍然需要弄清楚他们正在做的事情不是很好。

审查代码的目的是让第二眼（通常是经验更多的人）盯着它，以发现问题。如果您能够对他人的工作做出判断，并且有正当理由说某件事情不好，那么您就应该忽略自己作为审稿人的责任。

会有分歧，这是审稿人和被审稿人捍卫自己立场的机会。如果您是同龄人并且陷入僵局，请找一个资深的人打破平局。

这取决于发现了哪种问题

• 缺少copywrite通知-常见且无聊的问题，只是简要说明该问题并继续进行的简短评论
• 我可能会以不同的方式做事的地方-通常倾向于在这里问问题而不是发表声明，有时答案有时无法证明原始解决方案的合理性，然后我可以更明确地解决这些问题
• 在存在明显缺陷的地方，例如可以覆盖溢出的等值覆盖-达到红笔的位置-将其标记为缺陷，并非常清楚地指出其损坏的原因-还检查其他类似区域以检查是否没有系统性问题。

根据我的经验：

1. 审阅代码时，请始终与代码的创建者在一起。最好将代码投影在白板上，并且你们两个都可以很好地清楚地看到代码。

2. 进行友好的交谈。赞赏编码的大部分。如果您在代码中看到了一些不错的部分，请告诉他“这是我所见过的最好的东西”。

3. 请他检查您的代码，接受并同意有效点并纠正他。尊重您在代码中的注释，他将自动尊重您的代码审阅注释。
4. 除非非常重要或需要更多时间来纠正代码检查问题，否则请在开发人员级别进行处理。如果条件遗失问题，请不要升级为经理以求简单。
5. 从“向其他代码学习”的角度来看，而不是指出代码中的错误。
6. 在代码审查会议期间，请引用您过去犯的错误以及代码审查如何为您提供帮助并避免出现重大生产问题，因为另一组眼睛可以帮助您。
7. 要谦虚。更多的赞赏和对他的评论更少:)您将在代码审查中学到很多，他也将很乐意接受您的评论。