# 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` 之后
- **【强制】** 类变量放在类注释之后、所有类函数之前