CL描述信息的最佳实践
翻译腔依旧
Change List（CL） 是一个公开的，包含有“修改了什么”，以及“为什么修改“的记录。它会被永久的存储在版本控制系统里。并且，不仅仅是你的组员，其他部门甚至其他公司的工程师也常常会参考这些CL描述。
如果你的CL描述过于含糊，重点不明，或者只是简单的“修复bug”，“重构”，“重排格式”，那其他的工程师将很难通过仅仅阅读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正文中提及。如果有与之相关的设计文档，bug 号，基准测试的结果等，均应提供相应的链接。就算CL只有一行代码修改，也应尽量包含上下文信息。
最差实践示范
“fix bug” 是一种最没用的CL描述。工程师们无法获知：修复了什么bug？如何修复的？和它一样糟糕的描述还有：
- “Fix build.”
- “Add patch.”
- “Moving code from A to B.”
- “Phase 1.”
- “Add convenience functions.”
- “kill weird URLs.”
上述示例中都是真实案例。这些CL的作者可能相信他们已经提供了有用的信息，但是作为CL，只写这些并不足以让其他工程师们理解上下文。就好比你去读书之前，总是希望书的名字会告诉你接下来你会读的内容，比如《C++算法》就是讲C++和算法的。而《书》，《这是一本书》这种名字无疑会让读者摸不着头脑。
较好的cl描述示范
功能变更
rpc: remove size limit on RPC server message freelist.
Servers like FizzBuzz have very large messages and would benefit from reuse. Make the freelist larger, and add a goroutine that frees the freelist entries slowly over time, so that idle servers eventually release all freelist entries.
第一行用了寥寥数语描述了这个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.
Allowing Tasks to supply Now is a step toward eliminating the dependency on Borglet. Eventually, collaborators that depend on getting Now from the Task should be changed to use a TimeKeeper directly, but this has been an accommodation to refactoring in small steps.
Continuing the long-range goal of refactoring the Borglet Hierarchy.
第一行描述了这个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.
第一句话描述了改动是什么，正文则提供了此次改动的背景信息。 这样读者在阅读时即可了解背景而不用去搜索“为什么要把status.py的Build Rule由Python2 更改到Python3”。
