2.4 代码风格与可读性

2.4 代码风格与可读性

本节摘要：SOURCE 2.4 强调 PEP 8、有意义命名、注释、空行分块、Markdown 说明格，以及 black/autopep8 自动格式化。本节把这些建议落到 Notebook 场景：代码格写逻辑，Markdown 格写论证，并用 Mermaid 画函数调用关系辅助读者。

上手前先明确

阅读完本节，你应当能够：

1. 说明 PEP 8 对缩进、命名、行长的核心要求
2. 用 Markdown 单元格解释代码意图与实验结论
3. 在 nbextensions 或命令行使用 autopep8/black 格式化
4. 用 Mermaid 绘制简单流程图表达算法分支

一、PEP 8 与 Notebook 现实

SOURCE 建议遵循 PEP 8：4 空格缩进、函数名 snake_case、类名 CamelCase、每行约 79–99 字符、import 分组等。Notebook 里常见偏离是「一格塞 80 行」——应配合 1.3 节的 Ctrl+Shift+- 分割。

二、SOURCE 风格示例函数

SOURCE 给出带 docstring 的 calculate_average：

def calculate_average(numbers):
    """
    计算列表中数字的平均值。
    Args:
        numbers: 数字列表。
    Returns:
        平均值；空列表返回 0。
    """
    if not numbers:
        return 0
    return sum(numbers) / len(numbers)

data = [1, 2, 3, 4, 5]
print(f"The average is: {calculate_average(data)}")
​

Notebook 里函数定义格上方用 Markdown 写「为何算均值、异常值怎么处理」，下方 Code 格只留实现——一格一事（1.3 节）。

三、自动格式化工具

SOURCE 推荐 black、autopep8。命令行：

black notebook_export.py
autopep8 --in-place notebook_export.py
​

经典 Notebook 可装 Autopep8 nbextension（第 5 章详述），选中格一键格式化。JupyterLab 可绑 formatter 扩展。

⚠️ 常见坑：black 会改字符串引号与尾逗号——提交前 Run All 确认逻辑未变；Git diff 应针对 .py 模块而非巨大 ipynb 输出。

四、Mermaid 辅助可读性

SOURCE 2.4 用 Mermaid 画 calculate_average 流程：

Markdown 格内嵌此类图，比纯文字描述分支更清晰——平台 Vditor 直接渲染，无需额外插件。

代码格与 Markdown 格分工

函数调用关系示例（SOURCE）：

五、代码审查清单

SOURCE 还提 代码审查——Notebook 协作时用 Pull Request 看 Markdown+Code 变更；配合第 4 章 nbdime 可视化 diff。自查清单：

1. 变量名是否表达含义
2. 魔法数是否提成常量
3. 长格是否该拆或 %run 模块
4. 是否 Clear Output 再 commit

💡 关键直觉：Notebook 的可读性 = Markdown 叙事 + 短代码格 + 统一格式；读者先扫标题与图，再进代码。

温故知新

• PEP 8：缩进、命名、空行、docstring
• Markdown 格：背景、结论、Mermaid
• black / autopep8：自动统一风格
• Mermaid：流程与调用关系
• 审查：PR + nbdime，提交前 Clear Output

第 2 章完结；第 3 章在稳定内核与规范代码基础上，加速 pandas 探索与可视化。

一行代码的可读性自查

写每行代码前问三个问题：

1. 这行在表达什么业务含义？变量名能否直接读出意图。
2. 是否有重复计算，值得抽成函数或常量？
3. 逻辑是否藏在分支里，需要注释解释？

# 差：魔法数直接写
if df["age"] > 65 and df["health_score"] > 90:
    discount = 0.2

# 好：常量 + 命名条件
SENIOR_AGE = 65
HIGH_HEALTH_SCORE = 90
DISCOUNT_RATE = 0.2
is_senior_healthy = (df["age"] > SENIOR_AGE) & (df["health_score"] > HIGH_HEALTH_SCORE)
df.loc[is_senior_healthy, "discount"] = DISCOUNT_RATE
​

注释该写什么、不该写什么

注释解释"为什么"，不解释"是什么"。x = x + 1 # 自增 是废话；# 去除周末订单，避免节假日数据污染均线 才值得写。Notebook 里 Markdown 格承担解释职责，代码格内注释只留最必要的一两行。

black 接入后的工作流

1. 把 Notebook 导出成 .py：jupyter nbconvert --to script notebook.ipynb
2. black 格式化导出的脚本，检查 diff。
3. 若改动过大，先回 Notebook 改源，再导出重跑。
4. 正式代码放进 src/ 模块，CI 里加 black --check 门禁。

⚠️ black 默认会改字符串引号与长行换行，审 diff 时重点确认没有改变语义，而不是纠结引号。

与团队同步风格

格式问题是团队最容易吵架的点。约定越少越好：缩进交给 black，命名约定写进 README，docstring 模板统一放仓库根目录。review 时只讨论"变量名是否传神、边界是否处理"，把格式争议交给机器。

docstring 的三种格式选择

团队常用的 docstring 风格有三种：Google（Args/Returns 分节）、NumPy（带类型行）、reStructuredText（Sphinx 默认）。选哪一种不重要，重要的是全仓库统一。本教程示例用 Google 风格，因为它在 VS Code / JupyterLab 的 Shift+Tab 浮层里排版最友好。

def fit_with_report(model, X, y):
    """训练并返回评估摘要。

    Args:
        model: 已实例化的分类器。
        X: 特征矩阵。
        y: 标签序列。

    Returns:
        dict: 含 accuracy 与 f1 的摘要。
    """
    ...
​

长格拆分的经济账

一个 80 行的代码格，编译成 JSON 后 diff 单位是整个格：同事改了一行，你 review 时要读完全格。拆成三到五个短格后，每次改动只出现在对应格，审查成本直线下降。这是第 4 章能顺利协作的前提，也是 PEP 8 在 Notebook 场景最实用的翻译。

用 Mermaid 图约束代码结构

在写一段超过二十行的逻辑前，先花两分钟用 Mermaid 画出分支与数据流。图能暴露你逻辑里的重复路径和多余分支，改起来比改代码便宜。画完的图留在 Markdown 格里，既当设计文档又当读者导读，一举两得。

可读性的终极指标

一节代码可读性的检验标准很简单：一周后你自己或同事，能不能不看任何额外说明，只靠变量名、docstring 和 Markdown 格就讲清它做了什么、为什么这么做。讲不清，说明还得继续拆格、补注释、改命名。