Rules are laws. They are not just suggestions or recommendations, but strict, mandatory laws. As such, they are universally enforceable—rules may not be disregarded except as approved on a need-to-use basis. In contrast to rules, guidance provides recommendations and best practices. These bits are good to follow, even highly advisable to follow, but unlike rules, they usually have some room for variance.(规则就像法律。 它们不仅仅是建议或提议,而是严格的、强制性的法律。 因此,规则具有普遍可执行性——不得无视规则除非在需要使用的基础上获得豁免。 与规则相反,指导提供帮助建议和最佳实践。 指导值得遵循,甚至是高度建议能够遵守,但与规则不同的是,指导通常允许出现一些变化的空间。)
When defining a set of rules, the key question is not, “What rules should we have?” The question to ask is, “What goal are we trying to advance?” When we focus on the goal that the rules will be serving, identifying which rules support this goal makes it easier to distill the set of useful rules. At Google, where the style guide serves as law for coding practices, we do not ask, “What goes into the style guide?” but rather, “Why does something go into the style guide?” What does our organization gain by having a set of rules to regulate writing code?(当定义一组规则时,关键问题不是“我们应该有什么规则?”我们要问的问题是:“我们想要实现的目标是什么?”当我们关注规则将服务的目标时,识别哪些规则支持这个目标,可以更容易地提取有用的规则集。在谷歌,风格指南作为编码实践的法规,我们不会问,“风格指南中包含什么?”而是“为什么要把一些东西放进风格指南?”我们的组织通过制定一套规范代码编写的规则获得了什么?)
Setting the standard. When we advocate for consistency, we tend to focus on internal consistency. Sometimes, local conventions spring up before global ones are adopted, and it isn’t reasonable to adjust everything to match. In that case, we advocate a hierarchy of consistency: “Be consistent” starts locally, where the norms within a given file precede those of a given team, which precede those of the larger project, which precede those of the overall codebase. In fact, the style guides contain a number of rules that explicitly defer to local conventions[^6], valuing this local consistency over a scientific technical choice.(设置标准。 当我们提倡一致性时,我们倾向于关注内部一致性。有时,局部的惯例规则在整体惯例规则产生之前就已经出现了,因此调整一切来适应整体惯例规则是不合理的。在这种情况下,我们提倡一种层级的一致性:“保持一致性”从局部开始,一个文件中的规范优先于一个团队的规范,优先于更大的项目的规范,也优先于整个代码库的规范。事实上,风格指南包含了许多明确遵守局部惯例的规则,重视局部的一致性,而不是科学技术的选择。)
If conventions already exist, it is usually a good idea for an organization to be consistent with the outside world. For small, self-contained, and short-lived efforts, it likely won’t make a difference; internal consistency matters more than anything happening outside the project’s limited scope. Once the passage of time and potential scaling become factors, the likelihood of your code interacting with outside projects or even ending up in the outside world increase. Looking long-term, adhering to the widely accepted standard will likely pay off.(如果惯例已经存在,那么一个组织与外界保持一致通常是一个好主意。对于小的,独立的,生命周期短的项目,它可能不会有什么不同;内部一致性比发生在项目有限范围之外的任何事情都重要。一旦时间的推移和潜在的扩展性成为要素,代码与外部项目交互甚至最终与外部世界交互的可能性就会增加。从长远来看,坚持被广泛接受的标准可能会有回报。)
Our style guides also include limitations on new and not-yet-well-understood language features. The goal is to preemptively install safety fences around a feature’s potential pitfalls while we all go through the learning process. At the same time, before everyone takes off running, limiting use gives us a chance to watch the usage patterns that develop and extract best practices from the examples we observe. For these new features, at the outset, we are sometimes not sure of the proper guidance to give. As adoption spreads, engineers wanting to use the new features in different ways discuss their examples with the style guide owners, asking for allowances to permit additional use cases beyond those covered by the initial restrictions. Watching the waiver requests that come in, we get a sense of how the feature is getting used and eventually collect enough examples to generalize good practice from bad. After we have that information, we can circle back to the restrictive ruling and amend it to allow wider use.(我们的风格指南还包括对新的和尚未被很好理解的语言特性的限制。目的是在学习过程中,在一个功能的潜在缺陷周围预先安装安全围栏。同时,在每个人都应用起来之前,限制使用让我们有机会观察,从我们观察的例子中开发和提取最佳实践的使用模式。对于这些新特性,在开始的时候,我们有时并不确定该如何给予适当的指导。随着采用范围的扩大,希望以不同方式使用新特性的工程师会与风格指南的所有者讨论他们的例子,要求允许超出最初限制范围的额外用例。通过观察收到的豁免请求,我们了解了该特性是如何被使用的,并最终收集了足够多的示例来总结好的实践。在我们得到这些信息之后,我们可以回到限制性规则,并修改它以允许更广泛的使用。)
The decisions behind rules captured in our style guides are backed by evidence. When adding a rule, we spend time discussing and analyzing the relevant pros and cons as well as the potential consequences, trying to verify that a given change is appropriate for the scale at which Google operates. Most entries in Google’s style guides include these considerations, laying out the pros and cons that were weighed during the process and giving the reasoning for the final ruling. Ideally, we prioritize this detailed reasoning and include it with every rule.(在我们的风格指南中,规则背后的决定是有证据支持的。在添加规则时,我们将花时间讨论和分析相关的利弊以及潜在的后果,并试图验证给定的更改是否适合谷歌运营规模。谷歌风格指南中的大多数条目都包含了这些考虑因素,列出了在过程中权衡的利弊,并给出了最终裁决的理由。理想情况下,我们优先考虑这种详细的推理,并将其包含在每条规则中。)
The actual decision making for any style guide change is a discussion of the engineering trade-offs for the proposed modification. The arbiters make decisions within the context of the agreed-upon goals for which the style guide optimizes. Changes are not made according to personal preference; they’re trade-off judgments. In fact, the C++ style arbiter group currently consists of four members. This might seem strange: having an odd number of committee members would prevent tied votes in case of a split decision. However, because of the nature of the decision making approach, where nothing is “because I think it should be this way” and everything is an evaluation of trade-off, decisions are made by consensus rather than by voting. The four-member group is happily functional as-is.(对于任何风格指南的更改,实际的决策都是对提议修改的工程权衡的反复讨论。仲裁者在风格指南优化的一致目标上下文中做出决定。更改并非根据个人喜好。它们是权衡判断。事实上,C++风格仲裁组目前由四个成员组成。这可能看起来很奇怪:如果委员会成员人数为奇数,就可以防止出现出现意见分歧的情况,出现票数平手的情况。然而,由于决策制定方法的本质,没有什么是“因为我认为它应该是这样的”,一切都是一种权衡,决策是通过共识而不是投票做出的。这个由四名成员组成的小组就这样愉快地运作着。)
Guidance represents the collected wisdom of our engineering experience, documenting the best practices that we’ve extracted from the lessons learned along the way. Guidance tends to focus on things that we’ve observed people frequently getting wrong or new things that are unfamiliar and therefore subject to confusion. If the rules are the “musts,” our guidance is the “shoulds.”(指导代表了我们收集的工程经验的智慧,记录了我们从一路走来的经验教训中提取的最佳实践。指导往往侧重于我们观察到人们经常出错的事情或不熟悉并因此容易混淆的新事物。如果规则是“必须”,那么我们的指导就是“应该”。)