编码规范

为了统一C++编码规范,提高C++编码质量,制定本指南作为基线标准。这份文档是 TS C++编程风格规范的完整定义。当且仅当一个C++源文件符合此文档中的规则,才认为它符合 TS 的 C++编程风格。

本指南的目的是通过详细阐述 C++ 注意事项来驾驭其复杂性。这些规则在保证代码易于管理的同时, 也能高效使用 C++ 的语言特性。具体如下:

• 编码规范应该控制权重

当编码风格的规范能够带来足够的优点,这样才会要求所有工程师记住它。这个好处的衡量是相对的,如果一条规则反对的编程实践是人们无论如何都不会去涉及的,那么也不需要制定。例如,goto 语句违反了很多原则,但现在已经很少使用了,因此也就不需要在编程规范中进行讨论。

• 为维护者优化,而不是编码者

代码库(以及大多数独立的提交)是希望能持续相当长时间。结果,花在阅读代码上上的时间会远远多于写它的时间。我们明确地选择为普通软件工程师的阅读、维护以及调试代码的体验进行优化,而不是为了写代码时的便利。“给代码阅读者留下提示”是这个原则中一个独特的普遍的观点,在一个代码片断里面出现奇怪或者非常规的做法时(例如,传递指针所有权),在对应位置上为阅读者留下必要提示是很有用的(std::unique_ptr 表明在调用空间,指针所有权可以传递)。

• 与已有代码风格保持一致

代码采用一致性的风格可以让我们能关注到其他更重要问题(非常重要),这可以采用自动化工具来实现,它可以进行代码格式化或调整#includes,通过合理运用这种工具从而达到工具预设的一致性效果。很多情况下,规则的一致性需要归结到“只要选一个遵守就不用担心”,允许在规则上的灵活性的潜在价值已经远远胜于为此争吵花费的代价。

• 在合适情况下与更多 C++社团风格保持一致

参考其他开发团队 C++的编程风格对自己代码库的一致性是有意义的,如果 C++编码规范的一条规则解决了一个问题,或者说一些使用习惯是广为人知并且被接受的,那么这就是使用它的理由。然而,有时候这些编码规范的功能和使用习惯是有缺陷的,或者说设计的时候没有考虑代码库的需要。在这些情况下(如下所述)限制或者抛弃编码规范中的一些规则是合适的。例如:在一些情况下,我们倾向于使用本地代码库或者第三方库,而不是根据 C++标准设计的库。

• 避免奇怪或者危险的结构

C++有特性如果我们没考虑清楚将会是非常危险的。为了避免掉进这些陷阱,进行一些编程风格上的限制是有益的。由于缺乏这些规则经常会带来程序正确性降低的风险,因而也很难取消这些编程风格上的限制。

• 避免采用普通 C++开发工程师难以维护的结构

C++的有一些特性可能不是普适的,可能会引入复杂性。在广泛使用的代码中,它可能更倾向于使用这些复杂的编码结构,因为更复杂实现带来的优点是可以被广泛使用所加倍放大的,当一直工作在使用这样复杂结构的代码库中,理解这些复杂结构的成本并不会被加倍。当和编码规范冲突时,可以和项目主管讨论是否需要在特定的应用场景中,忽视检查与之对应的编码规则。这对于代码库是特别重要的,因为代码的维护者和团队的成员时常在更换,即使在这个代码库中某个部分代码上开发/维护的每个人现在都能理解,但是很难保证几年后还能有人理解。

• 考虑代码规模

对拥有达到百万行以上的代码以及数千 R&D 的代码库来说,每个人都能主动避免错误或者不必要的代码简化,将会为整个代码带来很大的贡献。例如:特别需要注意避免全局命名空间冲突:如果每个人都在全局空间命名变量的话,那么对上亿行代码来说,名字冲突的问题是难以处理和避免的。

• 必要时候性能为先

即使和这篇文档某些规则相冲突,性能优化有时候还是非常必要和合适的。

总体来说,这篇文档的目的就是提供对 C++特性进行合理限制的全面指导。和以往一样,着重常识和好的体验。对此重点参考了整个 Google C++社区既定惯例,而不仅仅是个人或者团队喜好。警惕和不要使用精巧或者非常规的结构:毕竟没有明确禁止和允许这样做是不一样的。