Python编码规范

缩进规范

• 使用四空格缩进
• 每行最大长度79个字符(flake8要求79个字符, pylint要求的规范是每行长度不能超过100个字符)

空行规范

• 全局的(文件级别的)类和全局的函数上方要有两个空行
• 类中的函数上方要有一个空行
• 函数内部不同意群的代码块之间要有一个空行
• 不要把多行语句合并为一行(即不要使用分号分隔多条语句)
• 当使用控制语句if/while/for时, 即使执行语句只有一行命令, 也需要另起一行
• 代码文件尾部有且只有一个空行(pylint要求结尾不能有空行)

空格规范

• 函数的参数之间要有一个空格
• 列表、元组、字典的元素之间要有一个空格
• 字典的冒号之后要有一个空格
• 使用#注释的话, #后要有一个空格
• 操作符(例如+, -, *, /, &, |, =, ==, !=)两边都要有一个空格, 不过当这些操作符在括号内时两边不需要空格

换行规范

• 一般我们通过代码逻辑拆分等手段来控制每行的最大长度不超过79个字符, 但有些时候单行代码还是不可避免的会超过这个限制, 这个时候就需要通过换行来解决问题了.
• 两种实现换行的方法：
  • 第一种, 通过小括号进行封装, 此时虽然跨行, 但是仍处于一个逻辑引用之下. 比如函数参数列表的场景、过长的运算语句场景
  • 第二种, 直接通过换行符\实现

文档规范

• 所有import尽量放在代码文件的头部位置
• 每行import只导入一个对象
• 当我们使用from xxx import xxx时, import后面跟着的对象要是一个package(包对应代码目录)或者module(模块对应代码文件), 不要是一个类或者一个函数
• import标准模块要放到import第三方模块之前, import自己写的模块放到最后, 每个类别之间加一个空格区分开.

注释规范

• 代码块注释, 在代码块上一行的相同缩进处以 # 开始书写注释
• 代码行注释, 在代码行的尾部跟2个空格, 然后以 # 开始书写注释, 行注释尽量少写
• 英文注释开头要大写, 结尾要写标点符号, 避免语法错误和逻辑错误, 中文注释也是相同要求
• 改动代码逻辑时, 一定要及时更新相关的注释

文档描述规范

• 模块文件、函数和类要写docstring;
• 三个双引号开始、三个双引号结尾；
• 首先用一句话简单说明这个函数做什么, 然后跟一段话来详细解释；
• 再往后是参数列表、参数格式、返回值格式的描述.

命名规范

• 变量名, 要全部小写, 多个词通过下划线连接(snake_case蛇形), 尽量不使用单字符等无意义的名字, 可以使用单字符变量名的场景, 比如for i in range(n)这种变量没有实际意义的情况
• 类的私有变量名, 变量名前需要加2个下划线_
• 常量名, 要全部大写, 多个词通过下划线_连接
• 函数名, 要全部小写, 多个词通过下划线_连接；类中不希望被外部访问到的函数, 以2个下划线_开头来命名
• 类名, 要求驼峰形式(CamelCase), 即单词首字母大写, 多个词的话, 每个词首字母大写然后直接拼接
• 命名需要做到名如其意, 不要吝啬名字的长度

代码分解

• 不写重复代码, 重复代码可以通过使用条件、循环、函数和类来解决
• 减少迭代层数, 让代码扁平化
• 函数拆分, 函数的粒度尽可能细, 也就是一个函数不要做太多事情
• 类的拆分, 如果一个类中有多个属性描述的是同一类事物, 就可以把这些属性拆分出来新建一个单独的类
• 模块化, 若项目偏大, 要为不同功能模块创建独立的目录(package)或文件(module), 通过import相互引用

其他规范

• try except中的except要加具体的错误类型.
• 项目根目录下要生成项目所需的模块版本列表:

1
2
3

pip3 freeze -l > requirements.txt
# 这样其他人可通过如下方式安装部署
pip3 install -r requirements.txt

• python3创建类时, 不需要显示继承object, 因为这个继承关系是默认的.

静态代码检测工具

使用pylint、flake8等命令工具, vim的syntastic插件, 各种IDE的相关插件等工具检查python文件编码规范.

各种python编码规范文档参考

• Style Guide for Python Code, Python官方的编码规范.
• Google Python Style Guide, Google公司的Python编码规范.
• The Hitchhiker’s Guide to Python, 这不只是Python的编程规范, 还是Python资源的集散地, 强烈推荐.

持续更新…