Python_编程中代码注释相关格式 PEP8 — Python 官方代码风格指南

一、代码布局（Code Layout）

1. 缩进

复制代码

使用 4 个空格作为一级缩进。
禁止使用 Tab，也不要混用空格和 Tab。

2. 行长度

复制代码

每行代码 不超过 79 个字符（注释和文档字符串建议不超过 72 字符）。
长表达式换行时，推荐使用括号隐式续行（而非反斜杠 \）。

bash 复制代码

# 推荐：使用括号换行
foo = long_function_name(
    var_one, var_two,
    var_three, var_four
)

3. 空行

复制代码

顶级函数和类之间用 两个空行。
类中的方法之间用 一个空行。
函数内部可用空行分隔逻辑块（谨慎使用）。

bash 复制代码

def func_a():
    pass


def func_b():
    x = 1
    y = 2  # 逻辑分段
    return x + y


class MyClass:
    def method1(self):
        pass

    def method2(self):
        pass

二、注释规范（Comments）

1. 原则

复制代码

注释应解释 "为什么" 而非 "做什么"（代码本身应自解释）。
注释必须 与代码同步更新，过时注释比没有更糟。

2. 文档字符串（Docstring）

复制代码

所有模块、类、函数都应有 docstring。
使用 三重双引号 """，遵循 PEP 257。
描述功能、参数、返回值、异常等。

bash 复制代码

def calculate_tax(income: float) -> float:

    """计算个人所得税
    

    :param income: 税前收入
    :return: 应缴税额
    """
    return income * 0.1

3. 行注释

复制代码

与代码至少留 两个空格，以 # 开头，首字母大写，句尾加句号。

bash 复制代码

x = x + 1  # Increment counter.

三、导入语句（Imports）

1. 导入顺序（分组，每组之间空一行）

复制代码

标准库（如 os, sys）
第三方库（如 requests, numpy）
本地应用/项目模块

bash 复制代码

# 标准库
import os
import sys
from datetime import datetime

# 第三方库
import requests
from flask import Flask

# 本地模块
from . import config
from myapp.utils import helper

2. 其他规则

复制代码

每行只导入一个模块（避免 import os, sys）。
避免通配符导入：from module import * 是禁止的。
优先使用 绝对导入，必要时才用相对导入。

四、其他重要建议

复制代码

命名一致性：
    变量/函数：snake_case
    类名：CamelCase
    常量：UPPER_SNAKE_CASE
空格使用：
    逗号后、二元运算符两侧加空格：a = b + c
    括号内不加空格：func(a, b) 而非 func( a, b )

工具推荐（自动检查/格式化）

复制代码

Black：自动格式化代码（强一致性）
Flake8：检查 PEP 8 违规
pylint / ruff：更全面的静态分析
在 CI 或 pre-commit 中集成这些工具，可强制规范落地。

✅ 总结：

Python 的布局规范核心是清晰、一致、可读。遵循 PEP 8 不仅提升个人代码质量，更是团队协作的基础。项目如有自定义规范，可在 PEP 8 基础上微调，但需确保组内统一。