v6ole/telecom-rd-project-template

Template

Files

T

v6ole b6a1fd85d8 feat: add China Telecom R&D project template

2026-07-28 22:30:20 +08:00

3.7 KiB

Raw Permalink Blame History

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