v6ole
107 lines
3.7 KiB
Markdown
107 lines
3.7 KiB
Markdown
# 02-Python 编码规范
|
||
|
||
> 以 PEP8 为基础，结合中国电信实际整理
|
||
|
||
## 1. 命名规范
|
||
|
||
### 包和模块
|
||
- **【强制】** 包命名全小写
|
||
- **【推荐】** 通过功能命名
|
||
- **【推荐】** 模块名全小写，多单词用下划线连接
|
||
|
||
### 类
|
||
- **【强制】** 驼峰命名（大写开头：`ClassName`）
|
||
- **【推荐】** 接口已文档化时可用函数命名风格
|
||
|
||
### 函数
|
||
- **【推荐】** 全小写，下划线连接单词（`do_something`）
|
||
- **【强制】** 单下划线 `_` 开头 = protected 模块函数
|
||
- **【强制】** 双下划线 `__` 开头 = 类内私有
|
||
|
||
### 变量
|
||
- **【强制】** 全小写，下划线连接
|
||
- **【强制】** 单下划线开头 = protected，双下划线开头 = 类内私有
|
||
- **【推荐】** 全局变量适用函数命名规范
|
||
|
||
### 常量
|
||
- **【推荐】** 全大写 + 下划线（`MAX_SIZE`）
|
||
|
||
### 异常类
|
||
- **【推荐】** 若抛出错误，异常名加 `Error` 后缀
|
||
|
||
### 通用原则
|
||
- **【推荐】** 名字使用英文单词，不能用拼音
|
||
- **【推荐】** 3~30 个字母，不超过 4 个单词
|
||
- **【强制】** 命名不能和关键字冲突
|
||
|
||
---
|
||
|
||
## 2. 注释规范
|
||
|
||
### 文件注释
|
||
- **【强制】** 使用文档字符串（三个双引号）
|
||
- **【参考】** 应包含：描述(Description)、作者(Author)、版本(Version)、日期(Date)、记录(Record)
|
||
|
||
### 类注释
|
||
- **【强制】** 类定义下必须有文档字符串
|
||
- **【推荐】** 有公共属性时，文档中应有 Attributes 段
|
||
|
||
### 函数注释
|
||
- **【强制】** 外部可见函数必须有文档字符串（非常短小/简单明了的除外）
|
||
- **【强制】** 文档字符串应描述做什么、输入/输出
|
||
- **【参考】** 使用 Args / Returns / Raises 格式
|
||
|
||
### 通用注释原则
|
||
- **【推荐】** 有效注释量 ≥ 30%
|
||
- **【强制】** 避免装饰性内容，保持简洁；避免行尾注释
|
||
- **【强制】** 复杂分支流程必须注释
|
||
- **【推荐】** 代码质量不高但能运行用 `# TODO:`；有隐患用 `# FIXME:`
|
||
|
||
---
|
||
|
||
## 3. 格式规范
|
||
|
||
### 缩进
|
||
- **【强制】** 4 个空格，禁止混用空格和 Tab
|
||
|
||
### 换行
|
||
- **【推荐】** 每行 ≤ 80 字符（导入语句和 URL 除外）
|
||
|
||
### 空行
|
||
- **【强制】** 顶层函数/类之间 2 个空行
|
||
- **【强制】** 类中方法之间 1 个空行
|
||
|
||
### 导入
|
||
- **【强制】** 每个导入独占一行（`import` 开头时）
|
||
- **【强制】** 导入顺序：标准库 → 第三方库 → 应用指定
|
||
- **【推荐】** 推荐绝对路径导入
|
||
- **【强制】** 禁止隐式相对导入（如 `import bench`）
|
||
- **【推荐】** 可使用显式相对导入（`from . import bench`）
|
||
|
||
### 字符串
|
||
- **【强制】** 避免循环中用 `+` 或 `+=` 累加字符串（用 `join`）
|
||
- **【推荐】** 同一文件内单/双引号保持一致
|
||
|
||
### 空值比较
|
||
- **【推荐】** 使用 `if foo is None:` 而非 `if foo == None:`
|
||
|
||
### 空格
|
||
- **【推荐】** 二元运算符两侧各一个空格
|
||
- **【强制】** 函数名和参数列表的 `(` 之间不加空格
|
||
- **【推荐】** 逗号、分号、冒号前面不加空格
|
||
|
||
### 关系运算
|
||
- **【强制】** 常量在左、变量在右（如 `if None is foo:`）
|
||
|
||
---
|
||
|
||
## 4. 安全编码（与安全分册交叉）
|
||
|
||
- **【强制】** 禁止在日志中保存口令、密钥
|
||
- **【强制】** 禁止使用私有/弱加密算法（必须用 SM4/SM2/SM3）
|
||
- **【强制】** 口令哈希存储必须加入盐值（至少 8 字节随机数，迭代 50000+ 次）
|
||
- **【强制】** 禁止硬编码敏感信息
|
||
- **【强制】** 使用强随机数（`secrets` 模块或 `os.urandom`）
|
||
- **【强制】** 类型变量定义统一放在 `import` 之后
|
||
- **【强制】** 类变量放在类注释之后、所有类函数之前
|