读懂别人的代码

学到这里，你写代码已经没问题了。但真实工作中，读代码的时间远多于写代码——尤其是学 AI，你要读大量开源项目。

---

拿到一个陌生项目，按这个顺序看

① README.md        —— 这是干什么的、怎么跑起来
② requirements.txt —— 用了哪些库，能推断技术栈
③ 目录结构         —— 代码是怎么组织的
④ 入口文件         —— main.py / train.py / app.py
⑤ 顺着入口往下追   —— 只追你关心的那条线

最重要的是第 ⑤ 步的「只追一条线」。新手常见的错误是从第一个文件开始逐行读完——几千行之后完全迷失。

正确做法：带着一个具体问题去读。 比如「数据是怎么加载的」，就只追 DataLoader 那条线，其他一律跳过。

---

典型的 Python 项目结构

project/
├── README.md
├── requirements.txt
├── .gitignore
├── src/  或  项目名/
│   ├── __init__.py       # 标记这是一个包
│   ├── data.py           # 数据加载
│   ├── model.py          # 模型定义
│   ├── train.py          # 训练逻辑
│   └── utils.py          # 工具函数
├── tests/
├── configs/              # 配置文件
└── notebooks/            # 探索性分析

看到这个结构，你应该能立刻猜到每个文件干什么——这就是遵守约定的价值。

---

几个必须认识的 Python 惯例

① if __name__ == "__main__":

def main():
    ...

if __name__ == "__main__":
    main()

含义：这个文件被直接运行时才执行 main()，被别人 import 时不执行。

为什么重要：没有它的话，别人 import your_module 会意外触发你的整个训练流程。

② __init__.py

标记一个目录是「包」，可以被 import。现代 Python 里可以省略，但看到它你要知道这是包目录。

③ 下划线开头的名字

写法	约定含义
_internal	内部使用，外人别调（只是约定，语法上仍可访问）
__private	类内部，会做名称改写
__init__ __len__	魔术方法，Python 自动调用

④ 类型标注

def train(model: nn.Module, epochs: int = 10) -> float:
    ...

Python 不强制执行类型标注（写错了也能跑），但它是极好的文档——读代码时先看函数签名，能省很多力气。

---

三个读代码的实用技巧

① 善用编辑器的跳转

VS Code 里 F12 跳到定义、Shift+F12 找所有引用。比手工搜索快十倍。

② 在关键位置插 print 或断点

print(f"[debug] batch shape={X.shape}, dtype={X.dtype}")

看形状比看代码更快理解数据流——尤其是深度学习代码，张量形状的变化就是逻辑本身。

③ 先跑起来，再读

能跑通的代码，读起来轻松十倍。因为你可以随时改一行、加个 print、看看结果变不变，用实验代替推理。

---

给代码写文档字符串

def normalize(x: np.ndarray) -> np.ndarray:
    """把数组缩放到 0-1 区间。

    Args:
        x: 任意形状的数值数组
    Returns:
        和输入同形状，最小值为 0、最大值为 1
    """
    return (x - x.min()) / (x.max() - x.min())

写文档字符串最大的受益者是三个月后的你自己——那时候你已经完全忘了当初为什么这么写。

练习：找一个 GitHub 上的小型 Python 项目（几百行即可），用上面的五步顺序读一遍，画出它的主流程。