diff --git a/zh-cn/review/developer/cl-descriptions.md b/zh-cn/review/developer/cl-descriptions.md index 7e760b2..335d7da 100644 --- a/zh-cn/review/developer/cl-descriptions.md +++ b/zh-cn/review/developer/cl-descriptions.md @@ -12,12 +12,14 @@ 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 描述的第一行应该是一个完整的句子，就好像是一个命令（一个命令句）。例如，“**Delete** the FizzBuzz RPC and **replace** it with the new system.”而不是“**Deleting** the FizzBuzz RPC and **replacing** it with the new system.“ 但是，您不必把其余的描述写成祈使句。 ## Body 是信息丰富的 {#informative} 其余描述应该是提供信息的。可能包括对正在解决的问题的简要描述，以及为什么这是最好的方法。如果方法有任何缺点，应该提到它们。如果相关，请包括背景信息，例如错误编号，基准测试结果以及设计文档的链接。 +如果你包含指向外部资源的链接，可能由于受到保留政策或访问限制影响，让未来的读者无法阅读。因此请尽可能可能包含足够的上下文，以供审阅者和将来的读者理解你的 CL。 + 即使是小型 CL 也需要注意细节。在 CL 描述中提供上下文以供参照。 ## 糟糕的 CL 描述 {#bad} @@ -39,6 +41,7 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 ### 功能更新 +示例: > rpc：删除 RPC 服务器消息 freelist 上的大小限制。 > > 像 FIzzBuzz 这样的服务器有非常大的消息，并且可以从重用中受益。增大 freelist，添加一个 goroutine，缓慢释放 freelist 条目，以便空闲服务器最终释放所有 freelist 条目。 @@ -47,6 +50,7 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 ### 重构 +示例: > Construct a Task with a TimeKeeper to use its TimeStr and Now methods. > > Add a Now method to Task, so the borglet() getter method can be removed (which was only used by OOMCandidate to call borglet's Now method). This replaces the methods on Borglet that delegate to a TimeKeeper. @@ -59,6 +63,7 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 ### 需要上下文的 小 CL +示例: > Create a Python3 build rule for status.py. > > This allows consumers who are already using this as in Python3 to depend on a rule that is next to the original status build rule instead of somewhere in their own tree. It encourages new consumers to use Python3 if they can, instead of Python2, and significantly simplifies some automated build file refactoring tools being worked on currently. diff --git a/zh-cn/review/developer/index.md b/zh-cn/review/developer/index.md index 6129eb7..df3a44f 100644 --- a/zh-cn/review/developer/index.md +++ b/zh-cn/review/developer/index.md @@ -4,6 +4,7 @@ - [写好 CL 描述](cl-descriptions.md) - [小型 CL](small-cls.md) +- 当 CL 指派给多个审查者时，用 WANT_LGTM 去表明期望得到 LGTM。你可以利用 WANT_LGTM=any (预设行为) 或 WANT_LGTM=all 去表明。 - [如何处理审查者的评论](handling-comments.md) 另请参阅[如何执行代码审查](../reviewer/)，它为代码审阅者提供了详细的指导。 diff --git a/zh-cn/review/reviewer/looking-for.md b/zh-cn/review/reviewer/looking-for.md index 3530edf..be824ed 100644 --- a/zh-cn/review/reviewer/looking-for.md +++ b/zh-cn/review/reviewer/looking-for.md @@ -44,6 +44,8 @@ CL 是否已经超过它原本所必须的复杂度？针对任何层级的 CL 请注意，注释与类、模块或函数的**文档**不同，它们应该代表一段代码的目的，如何使用它，以及使用时它的行为方式。 +也可以参考: go/comments + ## 风格 Google 提供了所有主要语言的[风格指南](http://google.github.io/styleguide/)，甚至包括大多数小众语言。确保 CL 遵循适当的风格指南。 diff --git a/zh-cn/review/reviewer/speed.md b/zh-cn/review/reviewer/speed.md index 4738153..6256515 100644 --- a/zh-cn/review/reviewer/speed.md +++ b/zh-cn/review/reviewer/speed.md @@ -22,7 +22,7 @@ 有一种情况下个人速度胜过团队速度。**如果您正处于重点任务中，例如编写代码，请不要打断自己进行代码审查。**研究表明，开发人员在被打断后需要很长时间才能恢复到顺畅的开发流程中。因此，编写代码时打断自己实际上比让另一位开发人员等待代码审查的代价更加昂贵。 -相反，在回复审查请求之前，请等待工作中断点。可能是当你的当前编码任务完成，午餐后，从会议返回，从厨房回来等等。 +相反，在回复审查请求之前，请等待工作中断点。可能是当你的当前编码任务完成，午餐后，从会议返回，从休息室回来等等。 ## 快速响应 {#responses} diff --git a/zh-cn/review/reviewer/standard.md b/zh-cn/review/reviewer/standard.md index c53aae5..92e0e0f 100644 --- a/zh-cn/review/reviewer/standard.md +++ b/zh-cn/review/reviewer/standard.md @@ -39,8 +39,8 @@ 如果在代码审查过程中有任何冲突，第一步应该始终是开发人员和审查者根据本文档中的 [CL 开发者指南](../developer/)和[审查者指南](index.md)达成共识。 -当达成共识变得特别困难时，审阅者和开发者可以进行面对面的会议，或者有 VC 参与调停，而不仅仅是试着通过代码审查评论来解决冲突。 （但是，如果您这样做了，请确保在 CL 的评论中记录讨论结果，以供将来的读者使用。） +当达成共识变得特别困难时，审阅者和开发者可以进行面对面的会议或视讯会议，而不仅仅是试着通过代码审查评论来解决冲突。 （但是，如果您这样做了，请确保在 CL 的评论中记录讨论结果，以供将来的读者使用。） -如果这样还不能解决问题，那么解决该问题最常用方法是将问题升级。通常是将问题升级为更广泛的团队讨论，有一个 TL 权衡，要求维护人员对代码作出决定，或要求工程经理的帮助。 **不要因为 CL 的开发者和审查者不能达成一致，就让 CL 在那里卡壳。** +如果这样还不能解决问题，那么解决该问题最常用方法是将问题升级。通常是将问题升级为更广泛的团队讨论，有个技术主管来权衡、要求维护人员对代码作出决定或要求工程经理的帮助。 **不要因为 CL 的开发者和审查者不能达成一致，就让 CL 在那里卡壳。** 下一篇：[Code Review 要点](looking-for.md)