Google C++ Style Guide

RWYQ阿伟 | 2025-02-05 | 笔记 | 0条留言 | 21 | 2025-02-05更新

---

原文地址：https://google.github.io/styleguide/cppguide.html

---

Background

C++ is one of the main development languages used by many of Google's open-source projects. As every C++ programmer knows, the language has many powerful features, but this power brings with it complexity, which in turn can make code more bug-prone and harder to read and maintain.

The goal of this guide is to manage this complexity by describing in detail the dos and don'ts of writing C++ code. These rules exist to keep the code base manageable while still allowing coders to use C++ language features productively.

Style, also known as readability, is what we call the conventions that govern our C++ code. The term Style is a bit of a misnomer, since these conventions cover far more than just source file formatting.

Most open-source projects developed by Google conform to the requirements in this guide.

Note that this guide is not a C++ tutorial: we assume that the reader is familiar with the language.

背景

c++是谷歌的许多开源项目使用的主要开发语言之一。每个c++程序员都知道，这种语言有许多强大的特性，但这种强大带来了复杂性，这反过来又会使代码更容易出错，更难以阅读和维护。

本指南的目标是通过详细描述编写c++代码时该做和不该做的事情来管理这种复杂性。这些规则的存在是为了保持代码库的可管理性，同时仍然允许编码人员高效地使用c++语言特性。

风格，也称为可读性，是我们所说的规范c++代码的约定。“样式”这个术语有点用词不当，因为这些约定涵盖的远不止源文件格式。

谷歌开发的大多数开源项目都符合本指南中的要求。

请注意，本指南不是c++教程：我们假设读者熟悉该语言。

Goals of the Style Guide

Why do we have this document?

There are a few core goals that we believe this guide should serve. These are the fundamental whys that underlie all of the individual rules. By bringing these ideas to the fore, we hope to ground discussions and make it clearer to our broader community why the rules are in place and why particular decisions have been made. If you understand what goals each rule is serving, it should be clearer to everyone when a rule may be waived (some can be), and what sort of argument or alternative would be necessary to change a rule in the guide.

The goals of the style guide as we currently see them are as follows:

• Style rules should pull their weight

• The benefit of a style rule must be large enough to justify asking all of our engineers to remember it. The benefit is measured relative to the codebase we would get without the rule, so a rule against a very harmful practice may still have a small benefit if people are unlikely to do it anyway. This principle mostly explains the rules we don’t have, rather than the rules we do: for example, goto contravenes many of the following principles, but is already vanishingly rare, so the Style Guide doesn’t discuss it.

• Optimize for the reader, not the writer

• Our codebase (and most individual components submitted to it) is expected to continue for quite some time. As a result, more time will be spent reading most of our code than writing it. We explicitly choose to optimize for the experience of our average software engineer reading, maintaining, and debugging code in our codebase rather than ease when writing said code. "Leave a trace for the reader" is a particularly common sub-point of this principle: When something surprising or unusual is happening in a snippet of code (for example, transfer of pointer ownership), leaving textual hints for the reader at the point of use is valuable (std::unique_ptr demonstrates the ownership transfer unambiguously at the call site).

• Be consistent with existing code

• Using one style consistently through our codebase lets us focus on other (more important) issues. Consistency also allows for automation: tools that format your code or adjust your #includes only work properly when your code is consistent with the expectations of the tooling. In many cases, rules that are attributed to "Be Consistent" boil down to "Just pick one and stop worrying about it"; the potential value of allowing flexibility on these points is outweighed by the cost of having people argue over them. However, there are limits to consistency; it is a good tie breaker when there is no clear technical argument, nor a long-term direction. It applies more heavily locally (per file, or for a tightly-related set of interfaces). Consistency should not generally be used as a justification to do things in an old style without considering the benefits of the new style, or the tendency of the codebase to converge on newer styles over time.

• Be consistent with the broader C++ community when appropriate

• Consistency with the way other organizations use C++ has value for the same reasons as consistency within our code base. If a feature in the C++ standard solves a problem, or if some idiom is widely known and accepted, that's an argument for using it. However, sometimes standard features and idioms are flawed, or were just designed without our codebase's needs in mind. In those cases (as described below) it's appropriate to constrain or ban standard features. In some cases we prefer a homegrown or third-party library over a library defined in the C++ Standard, either out of perceived superiority or insufficient value to transition the codebase to the standard interface.

• Avoid surprising or dangerous constructs

• C++ has features that are more surprising or dangerous than one might think at a glance. Some style guide restrictions are in place to prevent falling into these pitfalls. There is a high bar for style guide waivers on such restrictions, because waiving such rules often directly risks compromising program correctness.

• Avoid constructs that our average C++ programmer would find tricky or hard to maintain

• C++ has features that may not be generally appropriate because of the complexity they introduce to the code. In widely used code, it may be more acceptable to use trickier language constructs, because any benefits of more complex implementation are multiplied widely by usage, and the cost in understanding the complexity does not need to be paid again when working with new portions of the codebase. When in doubt, waivers to rules of this type can be sought by asking your project leads. This is specifically important for our codebase because code ownership and team membership changes over time: even if everyone that works with some piece of code currently understands it, such understanding is not guaranteed to hold a few years from now.

• Be mindful of our scale

• With a codebase of 100+ million lines and thousands of engineers, some mistakes and simplifications for one engineer can become costly for many. For instance it's particularly important to avoid polluting the global namespace: name collisions across a codebase of hundreds of millions of lines are difficult to work with and hard to avoid if everyone puts things into the global namespace.

• Concede to optimization when necessary

• Performance optimizations can sometimes be necessary and appropriate, even when they conflict with the other principles of this document.

The intent of this document is to provide maximal guidance with reasonable restriction. As always, common sense and good taste should prevail. By this we specifically refer to the established conventions of the entire Google C++ community, not just your personal preferences or those of your team. Be skeptical about and reluctant to use clever or unusual constructs: the absence of a prohibition is not the same as a license to proceed. Use your judgment, and if you are unsure, please don't hesitate to ask your project leads to get additional input.

风格指南的目标

我们为什么有这份文件？

我们认为本指南应该服务于几个核心目标。这些是所有规则背后的基本原因。通过将这些想法公布于众，我们希望能够为讨论打下基础，并让我们更广泛的社区更清楚地了解为什么会有这些规则，以及为什么会做出特定的决定。如果您了解每个规则服务的目标，那么每个人都应该更清楚何时可以放弃规则（有些可以），以及需要什么样的争论或替代方案来更改指南中的规则。

我们目前看到的风格指南的目标如下：

风格规则应该发挥自己的作用

        风格规则的好处必须足够大，足以证明我们所有的工程师都记住它。好处是相对于我们在没有规则的情况下获得的代码库来衡量的，因此，如果人们不太可能这样做，那么针对非常有害的实践的规则可能仍然有一点好处。这个原则主要解释了我们没有的规则，而不是我们有的规则：例如，goto违反了下面的许多原则，但是已经很少了，所以风格指南没有讨论它。

为读者而不是作者进行优化

        我们的代码库（以及提交给它的大多数独立组件）预计将持续相当长的一段时间。因此，阅读代码的时间比编写代码的时间要多。我们明确地选择优化我们的普通软件工程师在代码库中阅读、维护和调试代码的体验，而不是简化编写代码的过程。“为读者留下痕迹”是该原则的一个特别常见的子点：当代码片段中发生了令人惊讶或不寻常的事情（例如，指针所有权的转移）时，在使用点为读者留下文本提示是有价值的（std::unique_ptr在调用点明确地演示了所有权转移）。

与现有代码保持一致
        在我们的代码库中始终如一地使用一种风格可以让我们专注于其他（更重要的）问题。一致性还允许自动化：格式化代码或调整#include的工具只有在您的代码与工具的期望一致时才能正常工作。在许多情况下，归因于“保持一致”的规则归结为“只选择一个，不要担心它”；在这些问题上允许灵活性的潜在价值，被让人们争论这些问题的成本所抵消。然而，一致性是有限制的；当没有明确的技术论据或长期方向时，这是一个很好的决胜局。它更多地应用于本地（每个文件或紧密相关的一组接口）。一致性通常不应该被用作在不考虑新风格的好处的情况下以旧风格做事的理由，或者不考虑代码库随着时间的推移向新风格靠拢的趋势。

在适当的时候与更广泛的c++社区保持一致

        与其他组织使用c++的方式保持一致与我们的代码库保持一致具有同样的价值。如果c++标准中的某个特性解决了某个问题，或者某些习惯用法被广泛了解和接受，那么就有理由使用它。然而，有时标准特性和习惯用法是有缺陷的，或者只是在设计时没有考虑到我们的代码库的需求。在这些情况下（如下所述），限制或禁止标准特性是合适的。在某些情况下，比起c++标准中定义的库，我们更愿意使用自己开发的或第三方的库，这可能是出于对其优越性的考虑，也可能是由于将代码库转换为标准接口的价值不足。

避免令人惊讶或危险的结构

        c++的一些特性比人们一眼就能想到的更令人惊讶或更危险。一些风格指南的限制是为了防止落入这些陷阱。对这些限制的风格指南的放弃有很高的门槛，因为放弃这些规则通常会直接危及程序的正确性。

避免一般c++程序员会觉得棘手或难以维护的结构

        c++有一些特性可能不太适合，因为它们给代码带来了复杂性。在广泛使用的代码中，使用更复杂的语言结构可能更容易被接受，因为更复杂的实现的任何好处都会被广泛地使用，并且在处理代码库的新部分时不需要再次付出理解复杂性的成本。当有疑问时，可以通过询问项目负责人来寻求对此类规则的豁免。这对我们的代码库特别重要，因为代码所有权和团队成员会随着时间的推移而变化：即使每个使用某些代码片段的人都理解它，这种理解也不能保证在几年后保持下去。

注意我们的规模

        对于一个由1亿多行代码和数千名工程师组成的代码库，一个工程师的一些错误和简化可能会让许多人付出高昂的代价。例如，避免污染全局名称空间是特别重要的：如果每个人都将内容放入全局名称空间，那么跨越数亿行代码库的名称冲突将很难处理并且很难避免。

在必要时进行优化

        性能优化有时是必要和适当的，即使它们与本文档的其他原则相冲突。

        本文件的目的是在合理的限制下提供最大的指导。一如既往，常识和良好的品味应该占上风。通过这种方式，我们特别提到了整个b谷歌c++社区的既定惯例，而不仅仅是您的个人偏好或团队的偏好。对使用聪明的或不寻常的结构持怀疑态度，并且不愿意使用：没有禁令并不等同于允许继续进行。使用您的判断，如果您不确定，请不要犹豫，要求您的项目领导获得额外的输入。

博客内容遵循 署名-非商业性使用-相同方式共享4.0国际（CC BY-NC-SA 4.0）协议。

本文链接：https://rwyqboy.top/post/1890.html

版权声明：本文由阿伟的笔记本发布，如需转载请注明出处。

笔记 C++ 编程 ...