Skip to main content

项目规范

Flake8规范​

Flake8 是 PEP8 代码风格检查工具,主要检查以下内容

缩进​

4 个空格

行长度​

最多 79 字符（PEP8 严格）或 99 字符（宽松）

空行​

具体规则：

  • 模块顶级定义（类/函数）前后：2 个空行
  • 类内方法前：1 个空行
  • 导入组之间：1 个空行
  • 导入和代码之间：2 个空行

导入​

顺序：

  1. 标准库（stdlib）
  2. 第三方库（third-party）
  3. 本地模块（local）

每组之间 1 个空行

空格​

具体规则：

  • 二元运算符（=、+、-、*、/）前后各 1 个空格
  • 比较符（>、<、==、!=）前后各 1 个空格
  • 逗号后面 1 个空格
  • 冒号前面 0 个空格，后面 1 个空格（字典、类型注解）
  • 函数参数默认值的 = 前后不需要空格：def func(x=1):

命名​

常见规则：

  • 大驼峰: 每个单词首字母大写，无下划线
  • 蛇形命名: 全小写，单词间用下划线分隔
  • 常量蛇形 / 大写蛇形: 全大写，单词间用下划线分隔
  # 正确
  class MyClass:           # 类：PascalCase
      def my_method(self): # 函数/方法：snake_case
          my_var = 1       # 变量：snake_case
          CONSTANT = 10    # 常量：UPPER_SNAKE_CASE

  # 错误
  class myClass:           # 应该是 MyClass
      def myMethod(self):  # 应该是 my_method
          myVar = 1        # 应该是 my_var

未使用变量​

检查导入和变量，不要出现未导入的库

复杂度​

McCabe 循环复杂度：

10是行业共识的 “合理上限”—— 研究表明，复杂度≤10时，代码的可测试性、可读性、可维护性处于较好水平；超过10后，测试用例数量会指数级增加，bug率和维护成本大幅上升。

PEP257规范​

PEP257 是文档字符串Docstring规范

Docstring必须存在​

# 正确 - 模块有 docstring
"""这是模块的说明"""

# 正确 - 类有 docstring
class MyClass:
    """这是类的说明"""
    pass

# 正确 - 函数有 docstring
def my_function():
    """这是函数的说明"""
    pass

# 错误 - 没有 docstring
def my_function():
    x = 1
    return x

Docstring格式使用三引号​

# 正确 - 双三引号
def func():
    """这是 docstring"""
    pass

# 正确 - 单三引号
def func():
    '''这是 docstring'''
    pass

# 错误 - 单引号
def func():
    '这是错误的'
    pass

# 错误 - 双引号
def func():
    "这是错误的"
    pass

一行Docstring vs 多行Docstring​

一行 Docstring（简短）

# 正确 - 简短的 docstring 一行写完
def simple_func():
    """返回一个数字"""
    return 42

class SimpleClass:
    """简单的类"""
    pass

多行Docstring

# 正确格式
def complex_func(x, y):
    """计算两个数的和。

    这是更详细的说明，可以多行。

    :param x: 第一个数字
    :param y: 第二个数字
    :return: 两个数的和
    """
    return x + y

# 错误 - 第二行应该空一行
def complex_func(x, y):
    """计算两个数的和。
    这是更详细的说明。  # 错误：应该先空一行
    """
    return x + y

Docstring内容结构​

一行 Docstring：总结句 + 句号

def func():
    """返回用户名。"""  # 正确
    return "John"

def func():
    """返回用户名"""  # 错误：没有句号
    return "John"

多行Docstring：总结 + 空行 + 详细说明

# 正确格式
def divide(a, b):
    """计算两个数的除法。

    详细描述：这个函数用于数学计算。
    支持浮点数和整数。

    :param a: 被除数
    :param b: 除数
    :return: 除法结果
    :raises ZeroDivisionError: 当 b 为 0 时
    """
    if b == 0:
        raise ZeroDivisionError("除数不能为 0")
    return a / b

类的Docstring​

# 正确
class Calculator:
    """计算器类 - 提供基础数学运算功能。

    属性：
        precision: 计算精度

    方法：
        add: 加法
        subtract: 减法
    """

    def __init__(self, precision=2):
        """初始化计算器。

        :param precision: 结果精度，默认为 2
        """
        self.precision = precision

    def add(self, a, b):
        """计算两个数的和。

        :param a: 第一个数
        :param b: 第二个数
        :return: 和
        """
        return a + b

句号要求​

# 正确 - 有句号
def func():
    """这是一个函数。"""
    pass

# 错误 - 没有句号
def func():
    """这是一个函数"""
    pass

# 正确 - 多行也要有句号
def func():
    """这是一个函数。

    更多细节。
    """
    pass

空白行要求​

# 正确 - 短 docstring 和代码之间没有空行
def func():
    """简单函数"""
    x = 1
    return x

# 正确 - 长 docstring 和代码之间有空行
def func():
    """函数说明。

    详细描述。
    """

    x = 1  # 这里有空行
    return x

# 错误 - 短 docstring 后面有空行
def func():
    """简单函数"""

    x = 1  # 不应该有空行
    return x