我们是如何落实 Code Style Guide 的(Python 篇)

我们是如何落实 Code Style Guide 的(Python 篇)

最近年终,总是想谈谈过去一年的感悟和积累。接下来大概有几篇关于项目管理等等一些小方面的介绍,这篇文章主要介绍一下我们如何将 Python 编码规范真正落实到程序的实际开发过程中的。

编码规范选择

Python 作为灵活的脚本语言,在格式方面并不存在太多的限制(相对编译语言)。这样会导致一个比较蛋疼的问题:在项目开发过程中,由于个人的习惯和编码风格,导致程序缺少一个统一的标准,每个人的代码表现形式也不同。因此,在实际项目由于新人加入、老人退出过程中会产生比较高的模块维护成本。因此,在实际的项目开发中,选择一个编码标准也是比较重要的。

面对编码风格选择,比较常见的包括 PEP-8Google Python Style Guide。在最后,我选择了 PEP-8 作为项目中的实际应用标准,要求程序需要在满足编码要求规范的前提下进行编码。

除了对代码编码更个的要求以外,我们还对 import 等具体的细节进行了标准化。

尽量规范注释

在降低模块维护成本过程中,另外一个比较好的方式是尽量提供良好的代码注释。尽管这个算是一个和语言无关的老生常谈的问题,我只是想在这里提一下另外一个 PEP:PEP-0257,这里介绍了一种约定的 docstring 编写方法,对于编辑器而言,可以通过插件快速实现注释。

不过我考虑到对个人习惯的影响较大,这个 PEP 实际项目开发中并未作为实际开发规范,只是鼓励大家在项目中进行执行。

从规范到执行

从代码开发最初的规范约定是一回事,当回到开发过程中,开发者难免会因为个人的习惯或者疏忽等各种原因导致程序开发过程中程序编码风格不统一问题。因此在实际开发过程中,我们又需要通过工具保证程序在实际过程中能够帮助规范化或者检查格式错误。

借助社区的力量,我们最终选择了工具 flake8yapfisort。其中,flake8 用于检查我们的代码是否正确的执行了标准;yapf 工具用于快速进行 PEP-8 标准化,减少了人工修改的成本;isort 工具则是执行我们之前提到的 import 标准化工作。

yapf 是 Google 员工开发的一个 Python 格式化工具,它支持 PEP8 与 Google 编码标准,一些具体的使用方式可以查看项目的主页。在实际的项目落地过程中,你应该会遇到的一个问题是关于 flake8yapf 标准不一致导致一个通过另一个无法正常通过的问题。这一个方面,我们选择的方式是统一妥协成 flake8 的标准。对于 yapf 不支持的部分,我们建议活用 # yapf: disable 标记。

还有另一个问题是关于一些 flake8 本身的标准(或者说 PEP-8 标准)问题,比如 flake8 常见问题:E501 程序代码长度超过 79 个字符问题,我们实际编码过程中对这一标准做了适当妥协,允许最大单行字符串长度为 200。但是我们仍然建议缩小至 79 个字符内表示完。

从执行到检查

在最后一关,是我们的上线前检查。我们设置了代码质量检查关卡和系统集成测试。

在代码质量检查过程中,我们会对程序的实际代码质量进行评估。我们对代码质量进行打分,对于分值较低的代码不允许提交进入 master 分支。代码质量的检查,我们同样的采用了 flake8 工具作为统一标准。最后个人的代码质量,通过 Webhook 也会直接反馈在具体的项目管理工具中。

Licensed under CC BY-NC-SA 4.0
Built with Hugo
主题 StackJimmy 设计