缩进规范

  • 使用四空格缩进
  • 每行最大长度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要加具体的错误类型.
  • 项目根目录下要生成项目所需的模块版本列表:

    pip3 freeze -l > requirements.txt
    # 这样其他人可通过如下方式安装部署
    pip3 install -r requirements.txt
  • python3创建类时, 不需要显示继承object, 因为这个继承关系是默认的.

静态代码检测工具

使用pylintflake8等命令工具, 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 资源的集散地, 强烈推荐.

持续更新…