7  Python 代码风格

对于许多 Python 初学者来说，从 “零基础” 到能敲出一段勉强运行的代码，往往需要花费不少精力，在这个过程中，代码格式和风格常常被抛诸脑后。可别小看这些细节，从长远来看，不规范的代码就像一团乱麻，不仅自己后续维护时容易迷失方向，当项目复杂度上升、参与协作的人数增多，其他开发者面对这样的代码也会一头雾水，极大影响开发效率。

为此，本文将系统梳理 Python 代码编写的格式和风格要点，同时还会推荐几款实用的 VS Code 插件，并分享如何借助 AI 工具如 Copilot，让你的代码在保持规范的同时，编写过程也更加轻松高效。

有关 Python 代码风格的规范，最权威的参考是 PEP 8，它是 Python 官方的编码风格指南，涵盖了 Python 代码的方方面面，包括命名规范、缩进、空格使用、注释等。

7.1 缩进与空行

  • 4 个空格 代表一级缩进；别用 Tab。
  • 模块级逻辑（导入、数据加载、建模、绘图）之间留 1‑2 行 空行，让结构一目了然。
# Bad
import pandas as pd
df=pd.read_csv("sales.csv")
for y in df["year"].unique():
  subset=df[df["year"]==y]
  print(y,subset["profit"].mean())

# Good
import pandas as pd

df = pd.read_csv("sales.csv")

for y in df["year"].unique():
    subset = df[df["year"] == y]
    print(y, subset["profit"].mean())

7.2 行长度与换行（≤ 79 字符）

核心原则：让每一行保持可扫描性。

  1. 首选：用圆括号 / 方括号 / 花括号包裹后换行。
  2. 必要时（无括号且行极长）：使用 \，但反斜杠置于行尾，并让下一行缩进 4 空格。
  3. 长列表 / 参数：一个元素（或一个参数）一行，末尾加逗号，易于版本控制。
# Bad – 行太长且难读
ax.plot(df["date"], df["close"], label="Shanghai Composite Index Close Price")

# Good – 括号换行
ax.plot(
    df["date"],
    df["close"],
    label="Shanghai Composite Index Close Price",
)

# Good – 无括号时最后一招
total = price + cost + tax - discount - coupon \
    - special_offer

# Good - version2：可读性更强 (运算符放在行首，而非行尾)
total =   price + cost + tax \
        - discount \
        - coupon \
        - special_offer

7.3 换行：显示拼接与隐式拼接

Source: Python 语言参考手册：2. 词法分析

7.3.1 2.1.5. 显式拼接行

两个及两个以上的物理行可用反斜杠（\）拼接为一个逻辑行，规则如下：以不在字符串或注释内的反斜杠结尾时，物理行将与下一行拼接成一个逻辑行，并删除反斜杠及其后的换行符。例如：

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # 看来是个有效的日期
        return 1

以反斜杠结尾的行，不能加注释；反斜杠也不能拼接注释。除字符串字面值外，反斜杠不能拼接形符（如，除字符串字面值外，不能用反斜杠把形符切分至两个物理行）。反斜杠只能在代码的字符串字面值里，在其他任何位置都是非法的。

7.3.2 2.1.6. 隐式拼接行

圆括号、方括号、花括号内的表达式可以分成多个物理行，不必使用反斜杠。例如：

month_names = ['Januari', 'Februari', 'Maart',      # 这些是
               'April',   'Mei',      'Juni',       # 一年之中
               'Juli',    'Augustus', 'September',  # 各个月份的
               'Oktober', 'November', 'December']   # 荷兰语名称

隐式行拼接可含注释；后续行的缩进并不重要；还支持空的后续行。隐式拼接行之间没有 NEWLINE 形符。三引号字符串支持隐式拼接行（见下文），但不支持注释。

7.4 空格使用（记下面 三条 就够）

规则 Bad Good
运算符两侧留空格 roi=profit/cost roi = profit / cost
函数参数赋值不留空格 df.sort_values( by ="date") df.sort_values(by="date")
切片不留空格 series[ 1 : 5 ] series[1:5]

7.5 命名约定

  • 变量 / 列名：lower_case_with_underscores
  • 常量：UPPER_CASE
  • 避免 l、O、0 混淆。
# Bad
ProfitRate = df.Profit.mean()

# Good
profit_rate = df["profit"].mean()

7.6 注释与文档（四种常见场景）

  1. 行内注释：代码后留 2 空格再写 #。

    df["roe"] = df["net_income"] / df["equity"]  # 计算 ROE

  2. 逻辑分块注释：在复杂步骤前用一句话说明 目的。

    # ~~~~~ 计算年度收益并绘图 ~~~~~

# Step 1 —— 获取数据 ——

# Step 2 —— 清洗数据 ——

  3. 块注释：多行解释流程，用完整句子，首字母大写。

    # Author: Zhaojun Wang.
# Date: 2025/5/13
# Source: CSMAR >> 个股收益数据库.
# Goal: 
#    1. 计算个股年化收益率.
#    2. 绘制年化收益率分布图.

  4. 文档字符串（函数 / 类）：三引号包裹，首行一句话，空一行后详细说明（可选）。

    def annualized_return(r: float, n: int) -> float:
    """将单期利率转换为年化收益率。

    参数
    ----------
    r : 单期收益率，如 0.02
    n : 一年内的期数，例如月度数据则 n = 12
    """
    return (1 + r) ** n - 1
    # 查看函数的帮助文件: 会显示上述文档字符串
import anualized_return
help(annualized_return)

7.7 导入顺序

# Good
import datetime as dt          # 1. 标准库
import numpy as np             # 2. 第三方库
import pandas as pd
from utils.io import save_png   # 3. 本地模块

各组之间留 1 空行，避免 from module import *。

7.8 类型提示

即使暂时不写函数，也可以给变量加注解，IDE 会即时提示类型。

rate: float = 0.08
amount: float = 1_200.0
tax: float = amount * rate
  • 好处：pylance、mypy 可检查数值与字符串混用等低级错误。
  • 成本：仅多写 : 类型，对运行速度基本无影响。

7.9 自动格式化与 VS Code 工作流

需求 推荐工具 VS Code 插件 关键设置
统一排版 black Black Formatter “Format on Save”
语法 / 风格检查 flake8 或 pylint Python 扩展内置 "python.linting.enabled": true
导入排序 isort isort python.sortImports.onSave": true

一键配置示例

pip install black flake8 isort
# 在项目根目录创建 pyproject.toml
echo "[tool.black]\nline-length = 88" > pyproject.toml

Jupyter Notebook 中的 .ipynb 也支持 Format on Save：

  1. 安装 Black Formatter 插件。
  2. 在设置中启用 Jupyter: Format On Save。

7.10 AI 生成代码还要格式化吗？

  • LLM 输出 ≠ 100 % 合规：ChatGPT / DeepSeek 生成的代码常有混用 Tab、行长超标等问题。
  • 最佳实践：生成后立即 black 一遍，让代码自动落到团队风格，不折腾手动对齐。
  • 调试视角：格式一致、空行明确，才能快速定位 AI 可能漏掉的边界条件或隐蔽 Bug。

7.11 借助 AI 工具进行格式化

1. GitHub Copilot 插件

如果你已经在 VScode 中安装了 github copilot 插件，可以选中代码后，输入提示词 格式化，快速调整格式：

Copilot_01_format

2. 其他插件：Prettier, autopep8 等 如果不使用 github copilot，可以使用 Ctrl + Shift + P，输入 Format Document，快速调整格式：

如下几个 VScode 插件也可以实现格式化功能： - Prettier - Code formatter - Python autopep8 - autoDocstring

3. ChatGPT, DeepSeek 等

也可以在 ChatGPT 或 DeepSeek 中输入提示词快速调整格式，比如：

帮我按照 PEP 8 规范格式化如下 Python 代码，要求：
1. 不要对原文内容工作任何修改
2. 输出结果时，不要添加任何额外的文字

~~~ 贴入 Python 代码 ~~~

7.11.1 总结

按照本清单落实 缩进、空格、命名、注释、自动工具 五个核心点，你的脚本即可达“干净易读、工具友好”的 80 % 合规线。剩余细节交给 black + flake8 + isort，把精力留给金融建模与数据洞察。

- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/#whitespace-in-expressions-and-statements)