本规范旨在为 Python 项目的代码编写提供一致性指南。它遵循 Python 社区的 PEP 8 标准，并结合了通用的编程最佳实践。
1. 编码风格
1.1 缩进
- 使用 4 个空格 作为缩进，不要使用制表符（Tab）。
def example():if True:print("Use 4 spaces for indentation.")1.2 行宽
-
每行代码不应超过 79 个字符，对于文档字符串或注释，行宽不超过 72 个字符。如果代码行太长，可以使用显式换行符
\或利用小括号、方括号等自然换行。
# 长行的示例：
def function_with_long_arguments(arg1, arg2, arg3, arg4, arg5):pass
1.3 空行
-
在顶级定义（如函数、类）之间留出两个空行。
-
在方法定义和类定义内部的函数之间留出一个空行。
class MyClass:def method_one(self):passdef method_two(self):pass
1.4 空格的使用
- 函数调用时，不要在括号内添加空格：
print("Hello") # 正确
print( "Hello" ) # 错误
- 避免在以下情况中使用多余的空格：
- 列表、字典等容器的括号内不使用空格：
my_list = [1, 2, 3] # 正确
my_list = [ 1, 2, 3 ] # 错误
2. 命名规范（naming conventions）
2.1 变量、函数与方法
- 使用 snake_case 命名，即小写字母加下划线分隔单词。
def calculate_total():total_value = 0return total_value
2.2 类名
- 使用 CamelCase 命名法，即每个单词首字母大写。
class EmployeeManager:pass
2.3 常量
- 常量使用全大写字母，单词之间用下划线（underscores）分隔。
MAX_SIZE = 100
2.4 私有属性与方法
- 私有属性或方法使用前导单下划线
_来表示，不强制限制，但表示不应从外部访问。
class MyClass:def _private_method(self):pass
2.5 包名
全小写字母：包名通常应使用小写字母，不使用大写字母。可以使用下划线（_）来分隔单词，但更推荐直接使用小写字母连接。
- 示例:
mypackage或my_package
公司或项目前缀（可选）：对于公司内部项目，包名可以包含公司或项目的前缀，保证包的唯一性，避免内部冲突。
- 示例:
company_projectname
2.6. 特殊方法（魔术方法）
- 特殊方法（也叫魔术方法）是 Python 类中内置(built-in)的、以双下划线开头和结尾的方法。这些方法有特定的行为和用途，比如
__init__、__str__、__repr__等。 - 不要为普通方法使用双下划线，这种命名方式应只用于 Python 内部功能。
class MyClass:def __init__(self, value):self.value = valuedef __str__(self):return str(self.value)
3. 注释与文档
3.1 行内注释
- 行内注释应与代码对齐，并与代码留有至少两个空格的间距。
x = x + 1 # 增加计数
3.2 块注释
- 使用块注释为代码片段提供详细的说明，每行应以
#开头，并与代码对齐。 -
# 计算总值 # 如果项目为空，返回0 def calculate_total():pass
3.3 文档字符串（Docstring）
-
为每个模块、类和函数编写文档字符串，说明其功能、参数、返回值等。使用三引号
"""进行定义。def add(a, b):"""Adds two numbers together.:param a: The first number.:param b: The second number.:return: The sum of a and b."""return a + b
4. 代码结构
4.1 导入顺序
-
导入应按以下顺序排列，且每类导入之间用一个空行分隔：
- 标准库导入
- 第三方库导入
- 本地模块导入
import os import sysimport requestsfrom mymodule import MyClass
4.2 避免循环导入
- 避免模块之间的循环导入。如果遇到循环导入问题，可以将导入语句移到函数或方法内部，确保在需要时才进行导入。
5. 异常处理
5.1 捕获特定异常
- 避免使用裸
except，应尽量捕获特定的异常类型。try:result = 10 / 0 except ZeroDivisionError:print("Cannot divide by zero.")
5.2 使用 finally
-
如果代码块中有需要无论是否抛出异常都要执行的操作，应使用
finally。try:file = open("file.txt") finally:file.close()
6. 测试
6.1 编写单元测试
- 使用
unittest或pytest编写单元测试。确保每个函数和模块都有相应的测试覆盖。
6.2 保持测试的独立性
- 测试用例应保持相互独立，不依赖其他测试的执行结果。
6.3 测试命名
-
测试函数应以
test_开头，便于测试框架自动识别。def test_add():assert add(2, 3) == 5
