python编码规范

Python 编码规范主要遵循 PEP 8（Python Enhancement Proposal 8），这是官方推荐的编码风格指南，提升代码的可读性、可维护性和一致性。

1.基础格式规范
  (1)缩进
      必须使用4个空格缩进（禁止使用Tab，若编辑器混用，需将Tab转为4空格）。
      换行后缩进层级统一，避免混合缩进（如部分用2空格、部分用4空格）。
      行尾禁止有多余空格（可通过编辑器配置自动去除）。
  (2)行长度
      单行代码不超过 79 个字符（注释 / 文档字符串不超过 72 字符），超长时需换行：
      运算符后换行，缩进 4 空格（或使用括号自然换行）；
  (3)空行
      模块级：函数 / 类之间空 2 行，类内方法之间空 1 行；
      逻辑块：代码逻辑分段时用 1 个空行分隔（避免连续多个空行）；
      文件末尾：保留 1 个空行（编辑器通常自动处理）。
  (4)空格使用
      运算符两侧加空格：a = b + c（而非 a=b+c），但函数 / 关键字参数等除外：
      逗号、分号后加空格：list = [1, 2, 3]（而非 list=[1,2,3]）；
      括号内侧无空格：dict = {'key': 'value'}（而非 dict = { 'key': 'value' }）；
      函数调用或定义的参数列表中，等号两侧无空格（关键字参数）：

2.命名规范
  a.PEP 8 对不同类型的标识符有明确命名规则，核心是「见名知意」，避免拼音 / 无意义缩写：
  b.避免使用 Python 关键字（如 def、class、if）作为变量名；
  c.避免单字符命名（除非是循环变量 i/j、临时变量 x/y 等）；
  d.缩写仅使用通用约定（如 id、url、json），禁止自定义无意义缩写（如 usr 代替 user）。

3.语法与代码风格
  (1)导入规范
      导入顺序：标准库 → 第三方库 → 本地自定义库，每组之间空 1 行；
      禁止通配符导入：from module import *（会污染命名空间，无法明确依赖）；
      导入路径：绝对导入优先，相对导入仅用于包内；
      单行导入一个模块（避免一行多个导入）：
  (2)条件 / 循环语句
      if/for/while 后必须加空格，冒号后换行缩进；
      单行条件仅用于简单场景（避免超长单行）：
      循环中避免修改迭代对象（如 for i in list: list.remove(i)）；
      使用 in 代替索引判断：if 'key' in dict（而非 if dict.has_key('key')）。
  (3)函数 / 类定义
      函数 / 类必须有文档字符串（docstring），说明功能、参数、返回值：
      函数参数：优先使用默认值，避免过多参数（超过 5 个考虑用字典 / 数据类封装）；
      类的 __init__ 方法：初始化属性时避免复杂逻辑，仅做赋值；
      避免过长函数（单行函数除外）：单个函数不超过 50 行（复杂逻辑拆分为多个小函数）。
  (4)异常处理
      明确捕获异常类型（禁止裸 except）：
      异常信息包含具体原因（避免仅打印 "出错了"）；
      使用 with 语句（上下文管理器）处理资源（文件、数据库连接等）：

4.注释规范
  a.注释必须是英文（团队约定中文除外），且简洁准确；
  b.行内注释：用 # 分隔，与代码空 2 个空格，仅解释「为什么」而非「是什么」：
  c.块注释：用于解释复杂逻辑，每行以 # 开头；
  d.避免冗余注释（代码本身能清晰表达的无需注释）；
  e.废弃代码直接删除（而非注释保留，版本控制可追溯）。

5.其他最佳实践
  (1)类型注解：Python 3.5+ 推荐使用类型注解，提升代码可读性和可维护性：
  (2)避免全局变量：全局变量易导致副作用，优先用函数参数 / 类属性；
  (3)代码复用：重复逻辑封装为函数 / 类，避免复制粘贴；
  (4)兼容性：若需兼容多版本 Python，使用 six 等库，或明确标注支持版本；
  (5)工具校验：使用以下工具自动检查规范：
      flake8：PEP 8 合规性检查；
      black：自动格式化代码（强制符合 PEP 8）；
      isort：自动整理导入顺序；
      pylint：深度代码分析（规范 + 潜在 bug）。