始终追溯

<header> <h1>始终追溯</h1> <time class="meta" datetime="2026-05-18">2026年5月18日</time> </header> <p>关于提升代码理解能力的四维技巧的小建议。</p> <p>我之前写过关于阅读代码重要性的文章： <a href="https://matklad.github.io/2025/09/04/look-for-bugs.html" class="display"><em>Look Out For Bugs</em></a> 我默认的阅读方法是“预测式”：我实际上不会逐行阅读代码。而是尝试理解它要解决的问题，然后想象自己的解决方案，再阅读我脑海中与编辑器中所见之间的“差异”。非空的“差异”要么表示我理解中的错误，要么是改进代码的机会。</p> <p>这是二维阅读，理解一个时间点冻结的代码快照。通常这足以发现“感觉有点奇怪”的异常，值得进一步调查。</p> <p>理想的代码是无记忆的——它精确地解决当前的问题。大多数实际代码是马尔可夫式的——在时间 <code>T</code> 的代码形状不仅取决于问题描述，还取决于时间 <code>T - 1</code> 的代码形状。三维步骤是追踪代码随时间的演变， <a href="https://en.wikipedia.org/wiki/Where_Do_We_Come_From%3F_What_Are_We%3F_Where_Are_We_Going%3F#/media/File:Paul_Gauguin_-_D'ou_venons-nous.jpg"><em>Where Do We Come From? What Are We? Where Are We Going?</em></a>.</p> <p>接下来的步骤是理解<em>为什么</em>。当时我们在写这段代码时在想什么? 这里有“心智理论”的概念很有用。我个人学到这个词太晚了，所以让我为<a href="https://xkcd.com/1053/">今天的幸运一万名</a>做个简短介绍。心智理论是一种将自己置于他人处境的能力。不仅仅是设身处地（“我肯定会在那种情况下采取不同行动”），而是设身处地想其所想（“<em>我</em>不会那样做，但我理解<em>他们</em>为什么这么做”）。这是人们要学习的东西。实验设置是这样的：一个孩子在一个有玩具的房间里，一个洋娃娃坐在房间的另一端，问孩子“洋娃娃看到了什么？”。年龄较小的孩子从<em>自己的</em>视角描述房间，年龄较大的孩子开始直觉到洋娃娃的视角是不同的。</p> <p>所以，<em>这</em>就是阅读代码的目标——理解原作者在想<em>什么</em>以及<em>为什么</em>。</p> <hr> <p>废话少说，一些实用建议。首先，阅读 <span class="display"><a href="https://mislav.net/2014/02/hidden-documentation/"><em>Every line of code is always documented</em></a>,</span> 这篇文章非常好。</p> <p>第二，确保你能<em>毫不费力</em>地找到一段代码的演变过程。这比看起来难！仅仅<code>git blame</code>不是答案——要留意容易解决的问题和需要解决的问题之间的差距。</p> <p><code>git blame</code>回答了空间问题“每一行是如何出现在这个文件中的”，因为这有一个相对简单的UI——用提交哈希注释每一行。但这并不是大多数时候你问的问题！你不在乎文件！中间有一小段代码，你想知道<em>那一段</em>的时间历史。</p> <p>尽管我不喜欢在浏览器中工作，但 GitHub 的 blame 网页界面可能比本地默认的要好。它从 <kbd><kbd>y</kbd></kbd> 快捷键开始，该快捷键将类似下面的符号引用解析为</p> <figure class="code-block"> <pre><code><span class="line">https://github.com/tigerbeetle/tigerbeetle/blob/main/src/vsr/replica.zig</span></code></pre> </figure> <p>在 URL 中带有提交哈希的引用：</p> <figure class="code-block"> <pre><code><span class="line">https://github.com/tigerbeetle/tigerbeetle/blob/c54f613a2eb2a127a0ba212704e3fa988c42e5cb/src/vsr/replica.zig</span></code></pre> </figure> <p>这个提交哈希至关重要，因为它锚定了整个仓库——如果你从网页界面打开其他文件，它将以该提交的状态显示。这让你不仅仅局限于查看差异，还能吸收那个时间点的整个上下文。</p> <p>所以我通常的网络工作流程是：</p> <ul> <li> <kbd><kbd>ctrl</kbd>+<kbd>f</kbd></kbd> 查找我感兴趣的行 </li> <li> <kbd><kbd>b</kbd></kbd> 切换 blame </li> <li> 点击几次“blame prior to change”，重复使用 <kbd><kbd>ctrl</kbd>+<kbd>f</kbd></kbd> 返回我好奇的片段。 </li> <li> <kbd><kbd>cmd</kbd></kbd>-点击可能相关的提交，将其提交哈希固定在新标签页的 URL 中。 </li> <li> 然后，在提交页面，点击“Browse files”按钮，再按 <kbd><kbd>t</kbd></kbd> 转到其他文件。或者， <kbd><kbd>cmd</kbd>+<kbd>l</kbd></kbd> 聚焦浏览器地址栏，根据需要输入 <code>s/commit/tree/</code>（或返回），在差异和快照视图之间切换。 </li> </ul> <p>再次说明，我的目标不是注释文件上的差异，而是获得所感兴趣提交的“虚拟检出”。</p> <p>这种方法在我职业生涯的大部分时间都在使用，但我终于找到了在本地复现的方法。思路是“原地”追溯责任。不是使用<code>git blame</code>注释代码行，而是直接切换到历史提交。我有以下快捷键组合：</p> <p><kbd><kbd>, b l</kbd></kbd> 追溯行。它记录当前光标的 <code>$line</code>，运行 <span class="display"><code>git blame -L $line,$line</code></span> 找到引入该行的 <code>$commit</code>，然后运行 <span class="display"><code>git switch --detach $commit</code></span> 检出该提交。我有一个专用工作树来进行代码考古，所以不用担心破坏工作。此外，还有一个半心半意的尝试来维护“逻辑”光标位置，但效果不佳。有没有 git 命令可以直接告诉我“对于 <code>$sha-B</code>，<code>$sha-A</code> 中的 <code>$file:$line:column</code> 等价于什么？”</p> <p><kbd><kbd>, b p</kbd></kbd> 追溯父提交。就是切换到当前 <code>HEAD</code> 的父提交，类似 GitHub 上的“blame before this change”（但略有不同，因为它假设 <kbd><kbd>, b l</kbd></kbd> 是上一个命令）。</p> <p><kbd><kbd>, b u</kbd></kbd> 撤销上一次追溯操作，切换回上一个点。我<em>真的</em>喜欢在网络上，我可以 <kbd><kbd>cmd</kbd></kbd>-点击来创建探索的替代分支。理论上，这在本地也可以复制，但我更喜欢破坏性地改变磁盘上的单个工作树。偏好原地追溯的一个重要原因是 LSP、<code>./zig/zig build test</code>、<code>rg</code> 等都能正常工作。这对我来说比分岔路径的花园更重要，而撤销是一个可以接受的变通方案。</p> <p>最后，<kbd><kbd>, b w</kbd></kbd> 复制当前提交和行的 GitHub 链接，可以粘贴到浏览器中。现代版本控制领域的一个<em>巨大</em>问题是，以代码审查评论形式存在的绝对关键信息不属于 git 仓库的一部分，而是锁定在别人的专有数据库中。我利用一个周末的时间<a href="https://tigerbeetle.com/blog/2025-08-04-code-review-can-be-better/">未能解决</a>这个问题，只好不情愿地适应。在浏览器中打开提交还可以链接到 PR 及其讨论。</p> <p>实现这个 blame 工作流需要 <a href="https://github.com/matklad/config/b"} >...</p>