2022年 11月 9日

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
  • 博客:量化小站