English
Reading code means constructing an explanation of how a program produces some behavior. It is a different task from recognizing syntax. You need to identify relevant state, follow changes to it, and distinguish what the code guarantees from what you merely expect.
Begin with a question that can be checked: where is a timeout selected, why is a record rejected, or what happens after a request fails? This limits the part of the system you must understand. A useful reading result is a short explanation with file locations, assumptions, and an example that confirms or challenges it.
Prerequisites and connections: Basic programming (§2.1) and navigation tools (§8.2). Software architecture (§7.1) helps connect local code to larger components.
The Shape of the Skill: Building a Model You Did Not Design
A program has several structures at once. Files organize source text; calls describe possible transfers of control; data flow describes where values come from and where they go; runtime components may live in different processes. A directory tree alone does not reveal all of these structures.
Build your understanding at the level needed by the question. To change a retry limit, you may need the configuration path and request loop, but not the rendering system. Conversely, reading the loop alone is insufficient if the limit is overwritten during startup. Alternate between a small local reading and checking the surrounding interfaces.
Keep observations separate from interpretations. “The test sets this value to three” is an observation. “Three is the required default” is an interpretation that needs a specification or other evidence. Mark unresolved questions explicitly. This avoids turning an early guess into an assumption that controls the rest of the investigation.
Top-down reading starts from an entry point or component map and asks which part handles the question. Bottom-up reading starts from a concrete function or value and works outward through its callers and dependencies. Use the first to locate a likely path and the second to check what that path actually does. Neither requires understanding the whole repository before making progress.
Entering, Navigating, and Understanding Unfamiliar Code
Entering an Unfamiliar Codebase
First establish which program you are reading: repository revision, entry point, language and dependency versions, and relevant configuration. Find the build and test instructions, then run one small example if the environment permits. Documentation gives orientation; the running example connects that orientation to observable behavior.
Suppose a command-line option promises that zero disables retries, but requests still retry. Trace the value from argument parsing through configuration merging into the client and finally the retry loop. In Python, cli_retries or env_retries or 3 chooses the first truthy value. With cli_retries = 0 and env_retries = None, it produces three. The problem is in configuration selection, even though its symptom appears in the request loop.
If the intended rule is that an explicitly supplied command-line value wins, distinguish absence from zero. After parsing and validating values, select the first value that is not None. Check the cases of a missing option, zero, and a positive value, as well as conflicts between configuration sources. This exercise produces a model of precedence that transfers to timeouts, limits, and feature settings.
Tests help reveal intended and observed behavior, but passing tests can be incomplete or based on the same mistaken assumption as the implementation. A characterization test records what the current program does; it does not automatically establish what the program should do. Compare implementation, tests, documentation, and the user’s requirement where they disagree.
Navigating with Tools
Use text search to locate likely names, semantic navigation to follow definitions and references, and runtime observation to check a particular path. These methods answer different questions. A static reference list may miss reflection or registration by strings; one execution trace shows what happened for that execution, not every possible call.
Follow one concrete value and note where its representation changes. A timeout may begin as a string, become an integer in seconds, and later become milliseconds. Record the units and permitted values at each boundary. This often exposes errors more directly than reading every function in call order.
When the path crosses a queue or process boundary, a call hierarchy is no longer sufficient. Find the message schema, producer, consumer, and correlation identifier. Check whether work may be retried or delivered more than once (§7.1). Keep a small map of the locations you actually need; expand it when an unresolved dependency matters.
Understanding Why: Code Archaeology and Intent Reconstruction
Code can show how a behavior is implemented without explaining why it was chosen. History can supply missing context: a compatibility requirement, an incident, an earlier design, or a dependency that no longer exists. Use git log and the relevant diff to inspect a change, then look for its issue, review, or design discussion.
git blame identifies a commit associated with a line’s last change under the selected options. A formatting change can obscure the earlier decision; the last editor is not necessarily the designer or the cause of a defect. Read the surrounding change before inferring intent.
Treat unusual code as a question. A redundant-looking check may protect an old client, or it may now be unnecessary. Recover the condition it protects, determine whether that condition still applies, and test the proposed change. Historical explanation helps you make a current decision; it does not require preserving every past decision.
AI-Assisted Reading
AI assistance can suggest an entry point, summarize a module, or identify candidate callers. Ask for concrete file and symbol references, then inspect them. An explanation can sound coherent while describing a different revision, overlooking configuration, or inventing a call that does not exist.
Use the explanation to form a checkable prediction. For the retry example, ask which value reaches the client when the option is zero, then verify that value in a test or debugger. If the prediction fails, revise the model. Do not replace source inspection with repeated requests for a more confident summary.
What Changes With Mastery
You can answer a bounded behavior question with evidence and explain what remains unknown. You can also identify which part of your explanation depends on the current configuration or execution path.
Practice by tracing one feature in software you use. Write its entry point, the main data transformations, an important failure path, and one prediction to test. Then make a small change or explain the feature to another reader. Their questions reveal gaps that silent reading can leave unnoticed.
Resources
Books and Texts
Spinellis’s Code Reading uses real programs to teach navigation and comprehension; Code Quality adds evaluation of their structure. Feathers focuses on understanding and changing systems with limited test support. The Architecture of Open Source Applications connects implementation choices to design explanations. Petzold’s Code supports background understanding of computing layers rather than source-reading technique itself.
| Book | Role | Type |
|---|---|---|
| Spinellis, Code Reading: The Open Source Perspective | Techniques and cases for reading source | Depth |
| Spinellis, Code Quality: The Open Source Perspective | What makes code good or bad | Depth |
| Feathers, Working Effectively with Legacy Code | Reading and modifying undocumented code | Depth |
| Petzold, Code (2nd ed.) | Layered bottom-up comprehension model | Depth |
| Brown & Wilson, The Architecture of Open Source Applications (free; paid print optional) | Real-world codebase and architecture reading cases | Practice |
Practice, Tools, and Projects
Pick a bounded feature in a library or application you can run. Trace one input, inspect a failure path, and compare your explanation with a test or observation. Standard libraries are useful material, but some contain specialized optimizations; a smaller module can be a better first exercise. A reading group or small contribution supplies questions and feedback from other readers.
| Resource | Platform | Type |
|---|---|---|
| Reading your language’s standard library source | Language-specific | Practice |
| Open-source contribution | GitHub / GitLab | Practice |
| GitHub Open Source Guides (free) | opensource.guide | Entry |
| Tracing a feature in software you use | Local | Practice |
| Code reading groups | Local / community | Practice |
Navigation, Search, and History Tools
Combine the navigation tools of §8.2 with version history. Inspect definitions and callers in the relevant revision, and use history to recover a change’s context. Repository-wide and cross-repository search help locate uses, but returned examples may belong to different versions. Keep the distinction between an observed usage and a supported interface contract.
| Resource | Platform | Type |
|---|---|---|
| Editor navigation (jump-to-def, find-refs, call hierarchy) | §8.2 tools | Practice |
| git blame / git log archaeology | Git | Practice |
| Sourcegraph / GitHub code search | sourcegraph.com / github.com | Practice |
| GitHub Code Search documentation (free) | docs.github.com | Reference |
Traps
| Trap | Why it misleads | Better response |
|---|---|---|
| Reading every file before forming a question | Much of the code may be unrelated to the behavior. | Trace one observable behavior and expand as needed. |
| Trusting a passing test as the specification | The test may omit a boundary or encode a mistaken expectation. | Compare tests with requirements and counterexamples. |
| Confusing a trace with all possible behavior | Configuration and other inputs can select different paths. | State the observed conditions and inspect alternatives. |
| Inferring intent from the last editor | Mechanical changes can hide the original decision. | Read the relevant diff and its discussion. |
| Accepting an unverified explanation | A fluent summary can invent references or omit state. | Use source locations and a testable prediction. |
中文
读代码，是建立程序如何产生某种行为的解释。这与认出语法是不同的任务：你需要找到相关状态，追踪它怎样变化，并区分代码保证的性质与自己期待的行为。
从一个能够检查的问题开始：超时时间在哪里确定，某条记录为何被拒绝，请求失败后会发生什么？问题可以限定必须理解的系统范围。有用的阅读结果，是一段包含文件位置、假设，以及验证或质疑它的例子的解释。
前置知识与联系：基础编程（§2.1）与导航工具（§8.2）。软件架构（§7.1）帮助联系局部代码与较大组件。
这项能力的形状：建立一个不是你设计的模型
程序同时具有多种结构。文件组织源代码文本；调用关系描述控制可能怎样转移；数据流描述值从哪里来、到哪里去；运行时组件还可能分布在不同进程中。仅看目录树，无法了解这些结构。
根据问题决定理解的深度。修改重试上限，可能需要阅读配置路径与请求循环，而不必理解界面渲染系统。反过来，如果启动过程会覆盖上限，仅阅读循环也不够。应交替进行局部阅读和外围接口检查。
把观察与解释分开。“测试把这个值设为三”是观察；“规定的默认值是三”是解释，需要规范或其他证据支持。把尚未解决的问题明确记下来，避免最初的猜测变成支配后续调查的假设。
自顶向下阅读从入口或组件关系开始，寻找哪一部分负责当前问题；自底向上阅读从具体函数或数值开始，沿调用者与依赖向外理解。前者帮助定位可能的路径，后者检查这条路径实际做什么。两者都不要求先理解整个仓库才能取得进展。
进入、导航和理解陌生代码
进入陌生代码库
先确定自己阅读的是哪个程序：仓库版本、入口、语言与依赖版本，以及相关配置。找到构建和测试说明；环境允许时，运行一个小例子。文档提供方向，运行结果则把这些描述与可观察的行为联系起来。
假设某个命令行选项规定零表示禁用重试，但请求仍然重试。沿着参数解析、配置合并、客户端初始化，直到重试循环追踪这个值。在 Python 中，cli_retries or env_retries or 3 选择第一个真值。当 cli_retries = 0、env_retries = None 时，结果却是三。问题出在配置选择，尽管症状发生在请求循环中。
如果规则是显式提供的命令行参数优先，就应区分缺失与零。解析和验证数值后，选择第一个不是 None 的值。检查参数缺失、零和正数，以及不同配置来源相互冲突的情况。这样得到的优先级模型，也适用于超时、数量限制和功能设置。
测试有助于了解预期行为和实际行为，但通过的测试可能不完整，也可能与实现共享同一个错误假设。特征测试记录当前程序的行为，不能自动证明程序就应该这样运行。当实现、测试、文档和用户需求不一致时，应比较这些证据。
使用工具导航
用文本搜索定位可能的名称，用语义导航追踪定义与引用，再用运行时观察检查一条具体路径。这些方法回答不同的问题。静态引用列表可能漏掉反射或字符串注册；一次执行轨迹只说明这次发生了什么，不能列出所有可能的调用。
追踪一个具体的值，并标记它在哪里改变表示形式。超时时间可能起初是字符串，随后变成以秒为单位的整数，最后又转换为毫秒。记录每个边界的单位和允许值，往往比按调用顺序通读所有函数更容易发现问题。
当路径跨越队列或进程边界时，调用层次就不够了。需要找到消息结构、生产者、消费者和关联标识，并检查任务是否可能重试或重复投递（§7.1）。只记录当前需要的位置；某个尚未解决的依赖变得相关时，再扩展这份记录。
理解为什么：代码考古与意图重建
代码可以展示行为怎样实现，却未必解释为何这样选择。历史记录可能补上缺失的背景：兼容性要求、事故、旧设计，或已经不存在的依赖。用 git log 和对应差异检查修改，再查找关联的问题记录、审查或设计讨论。
在所选参数的规则下，git blame 指出某一行最后修改所关联的提交。格式调整可能遮住更早的决定；最后编辑的人不一定是设计者，也不一定造成了缺陷。推断意图之前，应阅读整次修改的上下文。
遇到不寻常的代码，先提出问题。看似多余的检查可能保护旧客户端，也可能如今已经不再需要。找出它保护的条件，判断条件是否仍然成立，再测试准备进行的修改。历史解释帮助你作出今天的决定，并不要求保留过去的每个决定。
AI 辅助阅读
AI 可以建议入口、概括模块或寻找可能的调用者。要求给出具体文件和符号位置，再自己检查。解释即使连贯，也可能描述另一个版本、忽略配置，或虚构并不存在的调用。
把解释转化为能够检查的预测。在重试例子中，预测参数为零时传到客户端的值，再通过测试或调试器验证。预测失败，就修正理解。反复要求一个更肯定的总结，不能代替检查源代码。
熟练之后会发生什么变化
你能够用证据回答一个范围明确的行为问题，并说明哪些部分仍不清楚；也能够指出解释中哪些部分依赖当前配置或执行路径。
可以追踪自己使用的软件中的一个功能，记下入口、主要数据变换、一条重要失败路径，以及一个待验证的预测。然后做一次小修改，或向另一位读者解释这个功能。对方的问题能揭示独自阅读时容易忽略的空缺。
资源
书籍与文本
Spinellis 的《Code Reading》用真实程序教授导航与理解，《Code Quality》进一步讨论结构评价。Feathers 关注测试支持不足时怎样理解和修改系统。《The Architecture of Open Source Applications》把实现选择与设计解释联系起来。Petzold 的《Code》主要补充分层计算的背景，并不直接教授源码阅读技巧。
| 书籍 | 作用 | 类型 |
|---|---|---|
| Spinellis，Code Reading: The Open Source Perspective | 源码阅读方法与案例 | 深入 |
| Spinellis，Code Quality: The Open Source Perspective | 什么让代码好或坏 | 深入 |
| Feathers，Working Effectively with Legacy Code | 阅读并修改无文档代码 | 深入 |
| Petzold，Code（第 2 版） | 分层的自底向上理解模型 | 深入 |
| Brown & Wilson，The Architecture of Open Source Applications（免费；纸质版可选付费） | 真实代码库与架构阅读案例 | 实践 |
实践、工具与项目
选择一个能够运行的库或应用，阅读其中范围明确的功能。追踪一个输入，检查失败路径，再用测试或观察比较自己的解释。标准库是有用材料，但某些部分包含专门优化；较小模块可能更适合作为首次练习。阅读小组或小型贡献，可以提供其他读者的问题与反馈。
| 资源 | 平台 | 类型 |
|---|---|---|
| 阅读自己语言的标准库源码 | 各语言专用 | 实践 |
| 开源贡献 | GitHub / GitLab | 实践 |
| GitHub Open Source Guides（免费） | opensource.guide | 入门 |
| 追踪自己使用的软件中的某个功能 | 本地 | 实践 |
| 代码阅读小组 | 本地 / 社群 | 实践 |
导航、搜索和历史工具
结合 §8.2 的导航工具与版本历史。在相关版本中检查定义和调用者，用历史恢复修改背景。仓库内与跨仓库搜索有助于查找用法，但结果可能属于不同版本。应区分观察到的用法与接口承诺支持的约定。
| 资源 | 平台 | 类型 |
|---|---|---|
| 编辑器导航（jump-to-def、find-refs、call hierarchy） | §8.2 工具 | 实践 |
| git blame / git log 历史调查 | Git | 实践 |
| Sourcegraph / GitHub code search | sourcegraph.com / github.com | 实践 |
| GitHub Code Search documentation（免费） | docs.github.com | 参考 |
陷阱
| 误区 | 为什么会误导 | 更好的做法 |
|---|---|---|
| 没有问题就逐文件通读 | 大量代码可能与所关心的行为无关。 | 追踪一个可观察行为，按需要扩大范围。 |
| 把通过的测试当成规范 | 测试可能遗漏边界或包含错误预期。 | 将测试与需求、反例进行比较。 |
| 把一次轨迹当作全部行为 | 配置和其他输入可能选择不同路径。 | 说明观察条件，并检查其他路径。 |
| 根据最后编辑者推断意图 | 机械修改可能掩盖原始决定。 | 阅读相关差异和讨论。 |
| 接受未经验证的解释 | 流畅的总结可能虚构引用或遗漏状态。 | 检查源代码位置，并提出可验证的预测。 |