python代码/编码规范：pep8和google的python代码规范

当所有代码均保持一致的风格时，阅读别人的代码沟通成本最低，特别是在理解大型代码库时效率提升很大。python使用的比较多的代码规范包括2种，分别如下：​​​​​

 

• pep8 python编码规范
• google python编码规范

pep8是python编码规范的事实标准，google python编码规范做了更多的说明，可以作为pep8的补充。这也意味着python社区开源贡献者基本都遵守pep8，但不一定遵守google的python编码规范。

一、pep8的一些规则

参考pep8的目录，摘取一些重要的规则，具体使用的时候可以通过工具来检测。

1.1 代码布局

• 每个缩进级别使用4个空格；连续行使用垂直对齐或者使用悬挂式缩进(额外的4个空格缩进)
• 空格是首选的缩进方法
• 每行最多79个字符
• 二元运算符前后换行都允许，只要代码保持一致就行。对于新代码建议在二元运算符前进行换行
• 空白行：使用两个空白行分隔顶层函数和类定义；类方法定义使用一个空行分隔；使用额外的空白行来分隔相关逻辑功能
• 文件应该使用UTF-8编码, 且不应该有编码声明
• 导入多个库函数应该分开依次导入；导入总是放在文件的顶部，在任何模块注释和文档字符串之后，在模块全局变量和常量之前；导入应按以下顺序进行：标准库导入、有关的第三方库进口、本地应用程序/库特定的导入，每组导入直接用空行分隔；避免通配符导入（import *）

1.2 字符串

• 单引号字符串和双引号字符串相同，代码保持一致即可
• 对于三引号字符串，常用三个双引号作文档字符串，文档字符串常用在模块的开端用以说明模块的基本功能，或紧跟函数定义的后面用以说明函数的基本功能

1.3 空格

• 避免使用无关的空格，包括空格内、逗号分号前面等
• 避免在行末使用空格
• 二元运算符在两侧使用一个空格
• 当用于指示关键字参数或默认参数值时，不要在=符号周围使用空格

1.4 使用尾部逗号(trailing commas)

• 尾部逗号通常可选，除了用来说明是只有一个元素的元组tuple时
• 当参数、值等列表期望经常扩展时，通常是每个值一行，再加上一个尾部逗号

1.5 注释

• 代码更改时，相应的注释也要随之高优更改
• 注释应该是完整的语句，第一个单词应该大写，除非它是特定标识符
• 块注释：缩进到与该代码相同的级别。块注释的每一行都以＃和一个空格开始
• 行注释：对某一语句行进行注释，注释应该与语句至少隔开两个空格，用＃和一个空格开始
• 对于公共的modules, functions, classes, and methods，需要写文档字符串
• 注释应该是完整的语句，第一个单词应该大写，除非它是特定标识符

1.6 命名约定

• python命名规范有点混乱，很难完全保存一致。对于新模块和包，应该遵守这些新的约定，已存在的库内部一致性更重要
• 命名应该反应其用途而非实现
• 不要将字符’l’（小写字母l），’O’（大写字母o）或’I’（大写字母I）作为单个字符变量名称
• 模块名应该使用简短、全小写的名字
• 类的命名采用驼峰命名法，即每个单词的首字母大写
• 函数名称应该是小写的，为了提高可读性，必须使用由下划线分隔的单词

二、google python编码规范的一些规则

相比pep8，google编码规范对怎么写代码的细节要求更多。比如怎么使用异常，文档字符串怎么写，Todo注释的使用等。参考规范目录摘取一些重要的规则说明

2.1 背景

• 可以使用yapf自动格式化工具来格式化代码

2.2 python语言规则

• 使用google的pylintrc配置文件来允许pylint
• 只对包和模块使用import语句，不对单个类或函数使用import
• 使用绝对路径导入每个模块
• 可以使用异常但必须非常小心。不要使用assert语句来验证api的参数值；最小化try/except代码块
• 避免全局变量

2.3 python风格规则

• 不使用分号作为行尾，不使用分号将2个语句放到同一行
• 不要在return语句或条件语句使用括号，除非使用括号来表示连续行或元组
• 每行最长80个字符，每个缩进级别使用4个空格，空行、空格跟pep8基本一致
• main文件使用#!/usr/bin/env python3 或#!/usr/bin/python3开头，绝大部分文件不需要使用#！开头
• 每个文件应该包含一个版权声明
• 使用 f-string，%操作符或者format函数来格式化字符串
• 使用TODO注释说明临时的、短期的解决方案

2.4 保持一致性

三、python编码规范检查工具

光有规范不行，需要有配套的检查工具，方便团队开发代码时统一遵守

比如我用pycharm来编写Python代码时，如果有出现不符合PEP 8规范的话，pycharm就会提示我，如图所示。

更多工具如下：

• pycodestyle -- pycodestyle是一款简单的代码检查工具，之前名字叫pep8，为了减少混淆改名成pycodestyle
• pylint -- pylint是代码检查工具，不能自动修改代码，有对于的配置文件，可以参考google开源的pylintrc配置文件
• PyFlakes -- 一个简单的python错误检查工具,通过解析源代码而不是import来检测不同的错误，通常只能检查出一些逻辑错误
• flake8 -- 针对PEPE8进行代码规范提示，是对PyFlakes，pycodestyle的封装
• autopep8 -- autopep8是一款将python代码自动排版为PEP8风格的工具，它使用 pycodestyle来决定哪部分代码需要格式化
• yapf--yapf是google开源的一个用于格式化Python代码的工具，可以一键美化代码，支持两种规范：PEP8和Google Style

四、交流

我发文章的几个地方，欢迎关注公众号，最新的文章会优先发布在微信公众号上。

• 微信公众号：诸葛说talk
• 博客：量化小站