每个开发人员都有自己独特的风格和编写代码的方法。我们的风格来自于我们学习编码的方式、我们以前的经验以及我们自己的一些个性。但是,我们还需要始终如一地在团队中工作,并且通常在大型和复杂的组织中工作。这意味着数十、数百或数千种独特的编码风格协同工作,并可能在单个代码库中发生冲突。

如果您的团队都在使用不同的方法、不同的风格和不同的偏好,这可能会开始产生问题。为了作为一个团队有效地运作,您需要能够统一这些不同的方法,以便您处理的所有代码都相对容易理解、易于扩展、不易出现错误并且更易于维护。

大多数团队已经建立了系统来帮助标准化他们的代码——通常是在小型团队的代码审查期间出现的非正式规则和标准。但是,随着团队和复杂性的增长,这些非正式的最佳实践还不够,您需要一种更明确的方法。在 Google,他们在其Python 样式指南中明确阐述了为开源项目创建一致 Python 代码的方法。

让我们看看 Google 风格指南是什么,他们是如何构建规则和指南的,以及不同的工程团队可以从中学到什么。然后我们将快速了解如何使用 Sourcery](https://calendly.com/tim-gilboy/sourcery-teams-demo-clone?month=2022-07)将自己的样式指南和最佳实践构建到代码中。

---

在我们深入探讨样式指南本身之前,我想快速指出什么是样式和什么是格式之间的区别。它们之间有一些重叠,但作为一般经验法则,格式化特别关注代码的美学方面 - 从行长到间距,再到引号和括号的使用等。样式指南可能包括一些这些元素(例如,在 Google 样式指南中,第 3 节的大部分内容都集中在格式化元素上),但主要集中在代码的更多结构方面,我们将在下面讨论。

为了处理格式化问题,有几个很棒的 Python 格式化工具,包括:

AutoPEP8

黑色

更漂亮

雅警卫队

---

Google 的样式指南由 40 多套在 Python 中使用的“注意事项”组成,分为两个关键部分 - Python 语言规则和 Python 样式规则。从广义上讲,语言规则用于定义 Google 如何在其代码中使用(重要的是不使用)和构建 Python 语言的不同元素。对于在给定语言中具有不同经验水平的团队而言,这是样式指南的一个至关重要的方面,因为它有助于围绕代码结构以及您的团队应该和不应该使用哪种类型的高级语言特性提供指导。

例如 -section 2.19说你不应该使用任何 Python Power Features,而2.10说你可以谨慎使用 Lambda 函数(前提是它们相对较短)。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--m5sbGuEB--/c_limit%2Cf_auto%2Cfl_progressive% 2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gaymnqvd9y6cd24hkypw.png)

样式规则部分更侧重于代码应遵循的格式和样式实践 - 从部分 3.2专注于行长到部分 3.16专注于命名实践。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--TY3DQ6Gc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto% 2Cw_880/https://dev-to-uploads.s3.amazonaws.com/uploads/articles/avylmt1x0oum53tw1c4b.png)

在样式指南的两个部分中,有三个主要原因或建议类别:

• 避免危险的建议 - 专注于减少严重的错误、极端形式的技术债务或监管/安全风险。

• 实施最佳实践的建议 - 专注于确保每个人都使用相同的最佳实践来确保可维护性。

• 确保一致性的建议 - 专注于确保代码的可读性、可扩展性和结构相似。

规则与指南

与大多数样式指南一样,Google 样式指南为编码时的方法创建了两种类型的建议——如何构建代码的规则和如何构建代码的指南。规则是关于如何以最少的异常来构建代码的明确要求,而指导原则是可能有异常的强烈建议。

在样式指南中融合规则和指南很重要,因为代码结构的某些方面如果存在差异,可能会导致巨大的麻烦。但对于大多数建议,让您的团队在特定情况下离开这些建议很有用。否则,如果一切都是严格的规则,那么您的团队可能没有足够的灵活性来运作,这可能会导致挫败感。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--TBo7DLZ0--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880 /https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ywtsfci2q4i1ruu4zx6m.png)

第 3.1 节 - 围绕分号的建议是显式规则的示例

[![第 3.18 节 - 关于函数长度的建议是一个指南示例,它对长度提供了广泛的建议,但为单个函数留下了灵活性。<br>

](https://res.cloudinary.com/practicaldev/image/fetch/s--jSxlOv7---/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws。 com/uploads/articles/zueue2vclg6btwtcyr3u.png)](https://res.cloudinary.com/practicaldev/image/fetch/s--jSxlOv7---/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https:// dev-to-uploads.s3.amazonaws.com/uploads/articles/zueue2vclg6btwtcyr3u.png)

第 3.18 节 - 关于函数长度的建议是一个指南示例,它对长度提供了广泛的建议,但为单个函数留下了灵活性。

避免危险的建议

谷歌风格指南只有一些属于“避免危险”类别的建议,它们涉及多个领域。它们主要是为了防止引入错误,但第 3.8.2 节还介绍了一些关于许可和 IP 要求的有趣规则,这些规则可能是开源项目中的关键标准。

2.5 全局变量[指南]

虽然没有完全禁止,但强烈建议不要使用全局变量,因为它们有在导入过程中改变模块行为的风险。这是样式指南中建议的一个主要示例,用于阻止可能显着增加项目中错误风险的编码样式。

2.12 默认参数值 [Guideline]

在整个风格指南中放置简单的指南(但不是全面禁止)有助于降低严重错误的风险。可以使用默认参数值,只要您不使用可变对象作为默认值。

2.18 线程[规则]

这是样式指南的另一部分,旨在限制错误风险,但不是因为主要用例是风险而创建要求,谷歌有一条规则,因为边缘情况的风险,不假设内置类型的原子性。

2.20 现代 Python:来自未来的导入 [Guideline]

Google 的许多开源项目都需要兼容各种 Python 版本。他们建议使用 from future import 语句来帮助使运行时版本转换更顺畅。该建议可能介于“避免危险”和“实施最佳实践”之间,因为它既有助于降低潜在错误的风险,又有助于加强围绕使用新功能的最佳实践。

3.8.2 模块[规则和指南]

风格指南中的关键要求不仅与代码的结构方式有关,还与业务要求、IP 要求和管理安全/声誉风险有关。作为样式指南更广泛的评论和文档字符串部分的一部分,谷歌明确要求每个模块都包含许可证样板。

3.11 文件、套接字和类似的有状态资源 [Rule]

除了错误风险和业务风险之外,样式指南中要考虑的另一个重要参数是确保围绕代码性能的最佳实践。在这里,Google 要求在使用完文件和套接字(以及其他类似的可关闭资源)后明确关闭它们,以确保您不会无意中消耗资源。

3.17 主要[规则]

对于测试和自动文档,Google 样式指南要求可执行文件的所有功能都存在于 main() 函数中,并且代码始终检查 if name u003du003d 'main' before执行代码。这延续了 2.5 中提出的一个重要方面,即您不应该在导入时直接执行代码。

执行最佳实践的建议

2.1 棉绒[指南]

如果您要求或建议您的团队使用某些工具或 linter,那么在您的样式指南中明确概述它是有用的。 Google 在这里列出了使用 Pylint 的建议(和限制)。

2.2 进口[规则]

我们都经常依赖导入(内部和外部),并且处理导入结构的方法不一致可能会导致混乱,并使我们将来更有可能在代码中引入错误。 Google 对如何导入模块和包以及在哪些有限的情况下可以将模块作为别名导入有明确的要求。

2.3 包[规则]

与上述规则类似,Google Style Guide 也对如何清楚地导入包有明确的规则。为了消除混淆,他们要求您按完整的包名导入每个模块。

2.4 例外[指南]

定义如何处理异常、错误和日志记录都是样式指南的重要方面,因为这里的不一致会很快导致您的代码变得过于复杂和难以理解。在这里,谷歌列出了一系列例外需要遵循的明确条件。

2.6 嵌套/本地/内部类和函数 [Guideline]

嵌套函数可能会导致严重的代码可读性问题,但也有一些用例非常有用。这个建议是一个有趣的例子,说明在风格指南中对问题采取中立立场是多么重要,因为它消除了关于你是否应该总是做某事的争论。在这种情况下 - 开发人员可以自行决定何时使用嵌套的本地函数或类,但有一些不鼓励使用的明确例外。

2.7 理解和生成器表达式 [Guideline]

该建议有助于创建非常明确的指导方针,说明何时可以使用理解或生成器表达式 - 它们需要是简单的情况并且需要放在一行中,否则不应使用它们。

2.8 默认迭代器和运算符 [Guideline]

我之前提到过,风格指南的一个关键部分是你应该利用并且应该避免的语言的内置特性。当涉及到支持类型的默认迭代器和运算符时,样式指南强烈建议您使用它们,因为它们简单高效。

2.9 发电机[指南]

与上述规则类似,Google Style Guide 鼓励使用生成器,因为它们提供更简单的代码。

2.10 Lambda 函数[指南]

与嵌套函数一样,Google Style Guide 表示可以使用 lambda,但仅限于特定情况,并不一定鼓励使用它们。它表明任何超过一行的内容对于 lambda 来说都是一个糟糕的用例。

2.11 条件表达式[指南]

在整个 Google 风格指南中,存在一个相当一致的主题。您应该使用 Python 功能来帮助使您的代码更短且更方便用于简单的单行用例,但可能不适用于更复杂的情况。条件表达式也是如此。

2.13 属性[指南]

像上面的几个建议一样,围绕属性的指南侧重于确保它们不会在它们会使事情变得过于复杂的情况下使用(例如,它们不符合典型属性访问的期望并且不实现您自己的属性描述符)。但是,就像上面的建议一样,它们不会阻止属性的整体使用

2.14 真/假评估 [指南]

Python 语言规则的所有部分都有一个优点和缺点部分,说明您可能希望或可能不希望使用该语言的给定功能的原因 - 这个建议可能有我最喜欢的缺点 - “C/C++ 开发人员可能看起来很奇怪”。总的来说,他们建议尽可能在 Python 中使用“隐式”错误,但他们提出的问题是在构建自己的样式指南时需要考虑的重要问题。确保你考虑谁将为你的代码库做出贡献,他们的背景是什么,以及这可能如何影响你应该如何构建你的最佳实践。

2.16 词法范围[指南]

与之前的一些有大量警告的建议相比,这个建议相对简单——使用词法作用域是可以的。

2.17 函数和方法装饰器[指南]

与其将本节的大部分内容花在是否使用装饰器上(它说可以明智地使用它们),样式指南的这一部分的大部分内容都侧重于在使用装饰器时如何处理它们——尤其是如何它们符合样式指南中的其他指南。

2.19 电源特性[规则]

在 Google 内部,有成千上万的开发人员使用各种语言编写代码,他们对 Python 拥有不同程度的专业知识和熟悉程度。在这里,开发人员被明确告知不要使用 Python 的“强大功能”,因为对于 a) 不熟悉它们或 b) 稍后重新访问代码的开发人员来说,它们可能难以理解。当您构建自己的风格指南时,重要的是要考虑您在团队中的体验变化以及您希望团队使用哪些类型的功能。

2.21 类型注释代码[指南]

有趣的是,类型注释是一个主题,在样式指南的两个单独部分中都有介绍——在 Python 语言规则部分和 Python 样式规则部分。这部分指南相对简单,只是说明强烈建议使用类型注释和类型检查。

3.15 获取器和设置器[指南]

这是另一个鼓励在您的代码中普遍使用某些类型的功能的部分 - 在这种情况下是 getter 和 setter 函数 - 但仅限于访问复杂的情况(不是更广泛)。

确保一致性的建议

我不会像前几节那样详细介绍一些一致性点以及它们为何有用,因为许多以格式为重点的建议相对简单。

3.1 分号[规则]

不要用分号终止行或使用分号在同一行上有 2 个语句。

3.2 行长[规则]

除了少数例外,最大行长度应为 80 个字符。

3.3 括号[指南]

一般来说,您应该谨慎使用括号

3.4 缩进[规则]

使用 4 个空格进行缩进。

3.5 空行[规则]

在顶级定义之间有 2 个空行,在方法定义与类行和第一个方法之间有 1 个空行,在 def 行之后有 0 个空行。

3.6 空格[规则]

Google Style Guide 在这里列出了一系列关于何时不应有空格的限制。

3.7 社邦线\【规则\】

仅在将要直接执行的文件中包含相关的 shebang 行(#!/usr/bin/env python3(以支持 virtualenvs)或#!/usr/bin/python3)

[3.8 评论和文档字符串 指南](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)

一致地构建注释和文档字符串对于推动项目的整体一致性和可读性非常重要。在这里,谷歌风格指南详细介绍了如何处理各种情况下的文档字符串的格式和结构,评论。

3.10 字符串[指南]

字符串格式的不一致会很快使代码变得混乱,并且很难阅读。在本节中,Google 样式指南针对结构化字符串(长字符串和短字符串以及 f 字符串)的一致性提供了明确的指导,并就如何构建和格式化日志记录和错误消息提供了明确的指导。

3.12 TODO 评论[规则]

管理复杂代码库的一个重要部分是考虑如何管理已知问题或已知的未来改进。这是一个明确的定义,你应该如何使用 TODO 注释——尤其是在 TODO 中引用了谁以及这意味着什么。

3.13 导入格式[Guideline]

在第 2.2 节中,有一系列关于如何处理导入以及如何构建它们的明确建议。相反,它专注于导入格式并设置导入应该在单独的行上定义的定义,导入应该在文件的顶部,并且它们应该从通用到特定。

3.14 声明[指南]

与最后几个建议类似,本节特别关注代码的格式和结构,以便在给定的行上只有一个语句。

3.16 命名[指南]

名字很难。不一致的命名会在项目中造成严重破坏。这也是我非常喜欢 Google 风格指南这一部分的原因之一。它概述了要避免的名称类型(单字符名称、冒犯性术语、要避免的特定字符等),给出命名约定以确保一致性,并给出代码不同方面的命名指南。

3.18 函数长度[指南]

您可以在您的风格指南中围绕代码质量要求(例如长度、复杂性、工作记忆等)提出各种各样的建议。在这里,Google 提出了函数长度(40 个字符)的建议限制,但也承认存在您可能需要违反该限制的例外情况。我喜欢这种给出强烈建议的方法,但不会将其作为样式指南中任何基于代码质量的部分的严格规则。

3.19 类型注释[指南]

不要与 2.21 Type Annotated Code 混淆,本节列出了一系列关于如何注释代码的指导方针,以及关于何时以及何时不注释代码的一些广泛指导方针

我需要风格指南吗?

谷歌的团队中有成千上万的软件工程师——所以你可能会认为,拥有一个明确的风格指南对于具有这种复杂程度的公司来说显然是件好事,但对于较小的组织来说却没有意义。但是,无论公司或团队的规模如何,同样的事实都将成立——阅读、交互和维护一段代码所花费的时间将比你要花的时间多几个数量级。正在花时间写它。这意味着您的团队从初始速度中以最适合每个人的方式编写代码所获得的任何收益很快就会被处理这些冲突方法的长期成本所吞噬。

如果您的团队还没有一套明确的(或一致的,但隐含的)代码标准、最佳实践和/或您遵循的准则,那么 Google 样式指南是一个很好的起点。查看完整的建议集,看看哪些适合您的团队的方法,然后删除或添加任何与您的团队更相关的规则。请记住,在您的团队的样式指南中没有一套客观的正确和错误建议,更重要的是您的团队都遵循相同的剧本,这有助于您的代码变得更加一致和有效。

将团队的最佳实践和风格指南转化为代码 →获取演示