Python编程规范+最佳实践

时间:2024-03-18 22:19:31

image

前言

Python之禅是影响Python编程语言设计的19条原则,也是Python编码规范的核心理念。

  • 优美胜于丑陋(Python 以编写优美的代码为目标)
  • 明了胜于晦涩(优美的代码应当是明了的,命名规范,风格相似)
  • 简洁胜于复杂(优美的代码应当是简洁的,不要有复杂的内部实现)
  • 复杂胜于凌乱(如果复杂不可避免,那代码间也不能有难懂的关系,要保持接口简洁)
  • 扁平胜于嵌套(优美的代码应当是扁平的,不能有太多的嵌套)
  • 间隔胜于紧凑(优美的代码有适当的间隔,不要奢望一行代码解决问题)
  • 可读性很重要(优美的代码是可读的)
  • 即便假借特例的实用性之名,也不可违背这些规则(这些规则至高无上)
  • 不要包容所有错误,除非你确定需要这样做(精准地捕获异常,不写 except:pass 风格的代码)
  • 当存在多种可能,不要尝试去猜测
  • 而是尽量找一种,最好是唯一一种明显的解决方案(如果不确定,就用穷举法)
  • 虽然这并不容易,因为你不是 Python 之父(这里的 Dutch 是指 Guido )
  • 做也许好过不做,但不假思索就动手还不如不做(动手之前要细思量)
  • 如果你无法向人描述你的方案,那肯定不是一个好方案;反之亦然(方案测评标准)
  • 命名空间是一种绝妙的理念,我们应当多加利用(倡导与号召)

PEP8是Python官方推出的编码规范。本规范以PEP8 编码规范作为出发点编写。
编码规范的第一原则是 提升代码的可读性,如果项目是从零开始请遵守该编码规范,如果不是,在项目和该规范出现冲突时,项目自身的规范优先。每一种规范分为强制和推荐。强制是必须遵守的规范,推荐是最佳实践。

代码布局

强制 :

  1. 统一使用4个空格缩进
  2. 单行最大长度为100
  3. 行数超过规定,建议用小括号()将多行内容连接起来,而不推荐使用反斜杠\进行连接。
  4. 不要在代码末尾加分号,也不要用分号将两条命令写在同一行
  5. 空行使用:
    1. 函数之间用两个空行隔开
    2. 类之间用两个空行隔开
    3. 类中方法用一个空行隔开
    4. 函数中不同逻辑代码块之间可适当插入空行
  6. 空格使用:
    1. 在二元运算符两边都要有空格。二元运算包括:算术(+ - * / ** )、赋值(=,+=,-=)、比较( ==, <, >, !=, in, not in, is, is not)、逻辑运算(and or not)、位运算(& | ! ~ >> <<)
    2. 函数关键字参数=两侧不需要空格。例: res = func(name="Tom")
    3. 逗号后面要加空格,但是如果后面是小括号则不用。例:List=[1, 2, 4]
    4. 冒号前不加空格,冒号后要加空格。但是切片里前后都不可加空格 。例:Dict = {key: value}
    5. 不要为对齐赋值语句而使用的额外空格

推荐 :

  1. import或函数存在续行的情况,遵守挂行缩进对齐
  • 第一行不应该有参数
  • 使用缩进以区分自己是续行

推荐:

def ats_import_dataset(
    db: Session = Depends(deps.get_db),
    ats_import: schemas.AtsDataSetImport,
    current_user: models.User = Depends(deps.get_current_active_user),
    controller_client: ControllerClient = Depends(deps.get_controller_client),
    background_tasks: BackgroundTasks,
 ) -> Dict:
  1. 在二元运算符之前应该换行,而不是在运算符之后换行

推荐:

income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

不推荐:

income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction - 
          student_loan_interest)

命名

强制 :

  1. 普通变量使用下划线分隔命名法,即蛇形命名法。例: max_value
  2. 变量名和Python关键字冲突,在变量末尾追加下划线。例: type_
  3. 避免使用双下划线开头并结尾的名称,该命令方式为python保留字。例:__ init__ 用于类初始化
  4. 常量用全大写字母,用下划线连接。例:MAX_VALUE
  5. 函数名遵循蛇形命名法。例:def get_user_info
  6. 类名使用驼峰命名法。例:class ControllerService
  7. 类中私有属性和方法用单下划线开头。该定义仅为君子约定,实例化可以访问。例:def _previate_fun()
  8. 类中不希望被继承的变量用双下划线开头。例:__user_info
  9. 模块应该用简短全小写的名字,如果为了提升可读性,下划线也是可以用的。
  10. 包使用简短全小写的名字,但不建议用下划线。

推荐 :

  1. 使用枚举值、常量值替换没有意义的数字
  2. 永远不要使用l(小写的L),O(大写的O),I(大写的I)作为单字符变量名,这些字符无法区分
  3. 描述性强。在可接受的长度范围内,变量名所指向的内容描述越精确越好。尽量不要用那些过于宽泛的词来作变量名 。推荐:last_login_datetime 不推荐:datetime
  4. 尽量短。命名尽量不超过5个单词。变量名要结合代码情景和上下文,可以通过函数名,类名,模块名自解释。
def get_expired_vip_users:
    pass

    # 返回过期vip用户数
    
    # 推荐
    users_count = 0 
    
    # 不推荐
    expired_vip_users_count = 0
  1. 配型匹配
  • 使用is,has, allow等开头来命名表示boolean类型。例:is_vip、has_error、all_empty
  • 使用_id结尾,length/count开头结尾的单词标示int类型。例:user_id,host_id,max_length,users_count

函数

强制:

  1. 函数设计要尽量短小,100行是一个参考值
  2. 一个函数只做一件事,保证函数语句粒度的一致性
  3. 禁止使用可变类型作为函数参数默认值,有惨痛教训 一个 Python Bug 干倒了估值 1.6 亿美元的公司
# 明令禁止
 List = []
 def fun(num, arr=List)
    pass

推荐 :

  1. 要将 self 作为实例方法的的第一个参数。
  2. 要将 cls 作为类静态方法的第一个参数。
  3. 如果函数的参数名和已有的关键词冲突,参考变量名和关键字重复的处理方法
  4. 函数圈复杂度可以衡量函数逻辑,圈复杂度不应该超过10(大概10个if else)

模块导入

强制:

  1. 一个import语句导入一个模块

推荐:

import os
import sys

不推荐:

import sys, os
  1. 导入总是位于文件的顶部,在模块注释和文档字符串之后,在模块的全局变量与常量之前
  2. 导入应该按照以下顺序分组,每一组导入之间加入空行:
  • 标准库导入
  • 相关第三方库导入
  • 本地应用/库特定导入
  1. 推荐使用绝对路径导入
  2. 禁止使用通配符的导入,污染命名空间。例: from module import *

推荐 :

  1. 如果导入的模块名较长,使用 as 给模块重命名。例:from moudle import module_fun as mf

注释

强制:

  1. 代码块注释使用 #, 接口注释使用 """
  2. 块注释应该至少离开代码2个空格,#后面跟一个空格
  3. 公共函数,重要的函数必须写接口注释
  4. 逻辑复杂,难以理解,脚本代码等情况必须要有注释
  5. 代码修改要同步更新注释

推荐:

  1. 待实现的功能用 TODO 注释
  2. 不要用注释描述代码,而是说清楚功能或逻辑

真值判断

推荐:

  1. 对于容器类型来说,判断空值不要用长度等于0,可以使用空序列布尔值为False这个属性来判断。

python 中 0、None、空字符串、空列表、空元组、空字典、空集合、空集合,都可以视为False,if 判断可以视为False。其他情况都为True。
推荐:

user_list = []
if not user_list:
    pass 

if user_list:
    pass

不推荐:

user_list = [] 
if len(user_list):
    pass 
if not len(user_list): 
    pass
  1. 布尔类型的判断,推荐使用 if value
greeting = True
推荐: if greeting:
不推荐: if greeting is True:
不推荐: if greeting == True:
  1. 对空值None的判断优先使用None为False属性,需要显示判断逻辑更加清晰时可以使用 is 关键字。例:if value is None
  2. 空值判断使用 if value is not None 而不是 if not value is None

错误捕获

强制 :

  1. 对于无法预知错误类型,使用异常捕获来保证流程正常。如网络请求
  2. 异常捕获的颗粒度是行,对大段代码进行 try-catch,这是不负责任的表现
  3. 异常捕获时分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。
  4. 异常不要用来做流程控制,条件控制
  5. 捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之。禁止在捕获错误之后使用pass不处理。如果不想处理它或不能处理,请将该异常抛给它的调用者。
  6. 禁止在 finally 块中使用 return,finally 是最后执行的代码,return会覆盖正常流程的return

推荐 :

  1. 存在if else 嵌套复杂的逻辑时,使用try except优化
  2. 可以通过预先检查进行规避时,推荐不要异常捕获来处理
  3. 错误的返回推荐异常类而不是变量

工程结构

推荐 :
Python项目没有其他语言如Java的Maven来构造固定的工程文件目录,结合Python社区推荐的工程目录制定推荐结构如下:

sample_project
 ├── readme.md
 ├── docs
 │   ├── api.yml
 │   └── public_read.md
 ├── requirements.txt
 ├── app
 │   ├── __init__.py
 │   ├── core.py
 │   └── helpers.py
 ├── config
 │   ├── mysql.py
 ├── deploy
 │   ├── __init__.py
 │   └── run.sh
 ├── db
 │ 
 ├── utils
 │ 
 └── tests
     ├── __init__.py
     └── test_basic.py

readme.md: 项目说明文件
docs: 存放项目文档,包括功能详细说明,api docs等
requirements.txt: 存放软件依赖的外部Python包列表
app: 存放项目接口主要代码的目录
config: 存放项目配置文件,如mysql,redis等配置项
deploy:存放部署文件,部署脚本等。如docker-compse.yml文件
db: 存放数据库相关代码
utils: 存放项目工具代码,通常和业务无关
tests: 存放单元测试文件