大家好,我是老王,前端时空的共建者。欢迎大家关注前端时空,并且来共同建设我们的前端时空社区。
今天跟大家分享一份来自 Google 团队的工程实践文档:
Google's Engineering Practices documentation。
这份文档是 Google 团队长期以来的内部项目最佳实践。其目的是帮助开发者更好地进行代码审查工作,通过 Code Review 来提升并优化当前项目的代码质量,便于开发人员维护和维护旧项目。
在国内,代码审查一直没有没有被重视,一般都是有了问题才去修修补补。但是,构建一个健壮的大型软件应用是必须有代码审查环节的。
如果你的团队开始代码审查环节,但没有正确的方法,这份文档就很适合你了。
我摘抄了一些片段。
首先,它包含两个部分
本节是基于过往经验编写的 Code Review 最佳方式建议。其中分为了很多独立的部分,共同组成完整的文档。虽然您不必阅读文档,但通读一遍会对您自己和团队很有帮助。
另请参阅代码开发者指南[7],该指南为正在进行 Code Review 的开发开发者提供详细指导。
代码审查时应该关注以下方面:
本节页面的内容为开发人员进行代码审查的最佳实践。这些指南可帮助您更快地完成审核并获得更高质量的结果。您不必全部阅读它们,但它们适用于每个 Google 开发人员,并且阅读全文通常会很有帮助。
另请参阅代码审查者指南[12],它为代码审阅者提供了详细的指导。
CL 描述是进行了哪些更改以及为何更改的公开记录。CL 将作为版本控制系统中的永久记录,可能会在长时期内被除审查者之外的数百人阅读。
开发者将来会根据描述搜索您的 CL。有人可能会仅凭有关联性的微弱印象,但没有更多具体细节的情况下,来查找你的改动。如果所有重要信息都在代码而不是描述中,那么会让他们更加难以找到你的 CL 。
CL 描述的第一行应该是关于这个 CL 是做什么的简短摘要,后面跟一个空白行。这是将来大多数的代码搜索者在浏览代码的版本控制历史时,最常被看到的内容,因此第一行应该提供足够的信息,以便他们不必阅读 CL 的整个描述就可以获得这个 CL 实际上是做了什么的信息。
按照传统,CL 描述的第一行应该是一个完整的句子,就好像是一个命令(一个命令句)。例如,“Delete the FizzBuzz RPC and replace it with the new system.”而不是“Deleting the FizzBuzz RPC and replacing it with the new system.“ 但是,您不必把其余的描述写成祈使句。
其余描述应该是提供信息的。可能包括对正在解决的问题的简要描述,以及为什么这是最好的方法。如果方法有任何缺点,应该提到它们。如果相关,请包括背景信息,例如错误编号,基准测试结果以及设计文档的链接。
即使是小型 CL 也需要注意细节。在 CL 描述中提供上下文以供参照。
“Fix bug ”是一个不充分的 CL 描述。什么 bug?你做了什么修复?其他类似的不良描述包括:
其中一些是真正的 CL 描述。他们的作者可能认为自己提供了有用的信息,却没有达到 CL 描述的目的。
英文不太好的同学不用担心的,国内的开发者早已将这份指南翻译成了中文。
下面是该项目的完整链接,感兴趣的小伙伴可以看一下。
[1]Code Review 标准: https://jimmysong.io/eng-practices/docs/review/reviewer/standard
[2]Code Review 要点: https://jimmysong.io/eng-practices/docs/review/reviewer/looking-for
[3]查看 CL 的步骤: https://jimmysong.io/eng-practices/docs/review/reviewer/navigate
[4]Code Review 速度: https://jimmysong.io/eng-practices/docs/review/reviewer/speed
[5]如何撰写 Code Review 评论: https://jimmysong.io/eng-practices/docs/review/reviewer/comments
[6]处理 Code Review 中的抵触: https://jimmysong.io/eng-practices/docs/review/reviewer/pushback
[7]代码开发者指南: https://jimmysong.io/eng-practices/docs/review/developer/
[8]风格指南: https://google.github.io/styleguide/
[9]写好 CL 描述: https://jimmysong.io/eng-practices/docs/review/developer/cl-descriptions
[10]小型 CL: https://jimmysong.io/eng-practices/docs/review/developer/small-cls
[11]如何处理审查者的评论: https://jimmysong.io/eng-practices/docs/review/developer/handling-comments
[12]代码审查者指南: https://jimmysong.io/eng-practices/docs/review/reviewer/