如何在 GitHub 正确吐槽

Question

背景

在几年前，百姓网几乎所有项目的开发流程就已经迁到 GitHub 上了。将 GitHub flow 作为日常开发流程，有一个很大的好处，pull request 很自然地成为 code review 的平台——每个人的代码都必须经过 review 之后，才会合并到主干。

因此，各个项目的 pull request 也逐渐成为一座座金矿，新人可以在历史 PR 中汲取经验，高手也常常通过 PR 追查疑难杂症的来龙去脉。而对我这个吐槽狂来说，PR 也是一个非常重要的阵地……

一个吐槽狂的日常

我叫魔法哥，我是一个吐槽狂。每当我在公司项目中看到不靠谱的代码，总是忍不住一吐为快。我相信，吐槽使人进步，吐槽改变世界。

吐槽很爽，但也有风险。即使某段代码看起来不太对劲，我也要再三确认，因为一旦搞错了，会很没面子。接下来，我会告诉你，我如何安全、优雅、正确地在 GitHub 吐槽别人的代码。

“这行代码是谁写的？”

看到不靠谱的代码，我们的第一反应通常是这个疑问。怨有头债有主，先要弄清楚喷谁。

我厂推荐使用 JetBrains 系列 IDE 来干活（公司出钱买正版），因此这里以 PhpStorm 为例，来还原一下我的工作场景。

对于启用了版本控制的项目，PhpStorm 允许我们查看每一行代码的作者信息。在行号处点击右键，选中 Annotate，即可开启此功能。（图一）

行号栏会扩展出一条作者信息栏，显示出每行代码所属的 commit 版本号、更新日期、作者等信息。当鼠标悬停在此栏时，还会显示每行的详细信息，包括完整的 commit 版本号、精确的更新时间、commit 的标题等。（图二）

“它是怎么变成现在这样的？”

根据上面的方法，我们就通常可以找到吐槽的对象了。但这还不够。有些时候这里显示出的作者可能是只重排了一下代码格式，并非真凶；又或者我们需要了解清楚代码是怎么一步步改成现在这样的，涉案人员都不能放过。所以接下来，我们要捋一遍这个文件的历史。

选择菜单 VCS → Git → Show History，PhpStorm 会在 Version Control 面板显示出当前文件的所有相关 commit 历史。（图三）

在这个历史记录中，双击任何一条 commit 即可查看它的 diff 视图。这样就可以深入分析某段代码的更改过程、定位到相应的 check-in 节点。（图四）

手边没有 IDE 怎么查？

如果自己的电脑不在手边，也可以用浏览器登录 GitHub 网站，通过网页界面来一步步追查。我们进入项目 repo 的主页，打开某个文件的详情页面，在顶部可以发现 “Blame” 和 “History” 两个按钮（图五）：

其中，进入 Blame 页面可以查看文件内每行代码的作者信息（图六），其功能相当于图一。

而进入 History 页面可以查看这个文件的所有修改记录（图七），类似于图三。

在 History 页面点击任何一条 commit 即可查看该 commit 各文件的 diff 视图（图八），相当于图四。

吐槽 Commit

追查到问题代码真正的 check-in 节点后，就可进入相关 commit 的详情页面开始吐槽了。慢着，如何找到某个 commit 在 GitHub 上的详情页？

如果你在 GitHub 网站进行追查，那么图八其实就是 commit 的详情页。此外，在图六 Blame 页面的左栏可以点击 commit 的标题或版本号直达该 commit 的详情页；图七中的每一行都链向每个 commit 的详情页。

如果你正在用 PhpStorm，且你的 PhpStorm 安装了 GitHub 插件，也比较好办。在类似图二的作者信息栏展开的状态下，右击任一 commit，在弹出菜单中选择 Open on GitHub，即可打开浏览器进入该 commit 的详情页。（图九）

（需要注意的是，由于我们的工作 repo 都是 fork，所以这个操作打开的页面是你的 fork 中的这个 commit。你需要手动修改一下页面 URL 来进入项目 upstream 的对应的 commit 页面。）

如果你的 PhpStorm 没有安装 GitHub 插件，也可以试试另一种方法。在图九的右键菜单中选择 Copy revision number，即可得到该 commit 的版本号。然后使用以下模式手工构造一个 URL 打开即可：

https://github.com/{org}/{project}/commit/{revision}

好了，在 commit 详情页的底部，我们可以发现一个评论框。（图十）

憋了这么半天，终于可以畅快地吐槽了！这个评论框具备完整的 GitHub 评论功能，我们可以使用 GitHub 风格的 Markdown 语法 书写富文本，可以引用其它 commit 或 PR、@ 别人、拖拽图片上传，很方便。

更优雅一点，吐槽 PR

在 GitHub 吐槽 commit 看起来很拉风，但这还不够，还可以更优雅一点。

上面说过，PR 是一座金矿，那里有很多讨论。找到某个 commit 所属的 PR，有助于我们更好地了解背景，避免喷错（安全第一啊）。

另一方面，当不良代码被合并到主干时，我们固然可以怪罪代码作者，但这更多是 review 者的责任。因为帮别人 review 代码的往往是有经验的资深工程师，帮助新人纠错和成长是他们的重要职责。因此，找到 PR 再吐槽，还可以揪出那些不认真 review 代码、“毁” 人不倦的导师们，直接打脸，岂不快哉！

那么，如何通过 commit 找到它所属的 PR 呢？

在上一节我们已经找到了 commit 的版本号，接下来，我们登录项目 upstream repo 的主页，在页面顶部有一个搜索框，填入 commit 的版本号，搜索。（图十一）

（请留意此时搜索框的状态是 “This repository”，否则你可能进错了的页面。）

搜索结果往往为空。别着急，在页面左侧的搜索类型栏可以发现 “Issues” 有 1 条搜索结果，点击之。（图十二）

此时就可以找到这个 commit 是在哪个 PR 被合并到主干的啦（图十三）。尽情开动吧！

做一个有情怀的吐槽狂

要知道，总会有一些害羞的同学不敢直面我的吐槽，他们总是假装没有收到我在 GitHub 的评论。为此，我写了这篇教程《如何正确接收 GitHub 的消息邮件》，并发给每个人，这样应该可以防止大家装睡了吧。

另外，在日常的吐槽工作中，我还会把一些典型的错误汇总起来，并招集大家听我当面吐槽一遍。虽然大家都很嫌弃我，但我丝毫不为所动，因为我是一个有情怀的吐槽狂，天生骄傲！