如何写出一篇令人愉悦的公关稿

我刚开始第一份工作的时候，写不出好的拉取请求（PR）。一开始，我完全不知道PR里应该包含什么，也不知道为什么要写PR。我当时以为只要把代码作为PR提交，然后审核的人就会处理剩下的事情。感觉很简单。

我真是大错特错了，因为每次我提交 PR，都会涌来一大堆评论（真的很多）。这导致需要重构，重构又会引发更多评论，如此循环往复。直到一周后，一切终于完成，而我却感觉像这样：

那不是如释重负的感觉。PR关闭合并后，我反而会感到愤怒。愤怒于浪费了大家的时间，愤怒于事情发展到这种地步，也愤怒于自己不止一次地让这种事发生。

好消息是，我的 PR 质量有了很大的提升。现在，我的 PR 里会收到一些高于代码检查工具级别的评论。事实上，我现在很期待其他开发者查看我的代码，而且我觉得他们也挺喜欢阅读我的 PR（当然，也只能做到他们能读懂的程度了）。

这篇文章将帮助你提升撰写和管理 PR 的方式，让你写出的 PR 能够给读者带来愉悦的阅读体验。不过，你可能会问，为什么要让你的 PR 给读者带来愉悦感呢？

为什么你应该改进你的个人最佳成绩，让它们带给你快乐

改进代码审查不仅对你有益，也能帮助其他人更好地帮助你。以下是编写更高质量的 PR 的主要好处：

1. 这样做会体现你对团队成员时间的尊重：时间是不可再生资源。既然如此，你难道想把他们当成你的私人代码检查员，白白浪费他们的时间吗？你应该尊重代码审查者的时间，让你的 PR 成为一种享受，而不是给他们端上一大盘乱七八糟的代码。
2. 减少重构时间，增加构建时间：反馈轮次越少，你就能有更多时间处理问题，从而提升你的声誉和能力。声誉和产出的提升通常会带来实实在在的好处，比如更多的收入（谁不爱钱呢？）。
3. 提升学习效果：如果审阅者不必花费太多时间充当你的个人质量保证，他们就能将更多精力集中在你的提升领域。他们不会只指出粗心大意的错误，而是会指出如何编写更优质的代码。

现在你知道了为什么，让我们来看看难点——怎么做。

如何编写更好的拉取请求

准备一份检查清单

刚开始的时候，你肯定会在提交个人最佳成绩（PR）时犯错。一两次没关系，但如果超过两次，那就太不礼貌了。

如果你的同事总是指出你提交的 PR 中存在同样的错误，例如代码中残留 `console.log` 语句，或者没有遵循既定的命名规范，那就把这些错误添加到检查清单中。每次提交 PR 之前，都对照清单检查一遍。

以下是我目前的检查清单。这是一份动态更新的清单，我会不断修改完善。

PR Checklist
- Console.logs
- Naming conventions
- Unused comments
- Unused CSS
- Design patterns match rest of codebase
- No if else

提交 PR 时难免会犯一些低级错误。别担心，只需把这些错误添加到你的检查清单中即可。同时，也要注意你犯的错误模式，并将它们也添加到清单中。关键在于不要让错误频繁发生，因为这会让审阅者觉得你不尊重他们的时间。

我认为将接下来的几项技巧添加到你的清单中是个好主意，但在添加之前，让我们先回顾一下这些技巧。

提交之前，先离开一会儿，过段时间再重新审视自己。

在提交任何 PR 之前，我都会暂时放下代码，至少几个小时，理想情况下我会睡一觉再看。

第二天你再来看代码，你会发现它已经面目全非。你甚至可能会纳闷，这堆乱码是谁写的（其实是你自己写的！）。没关系，这正是你想要的。如果你第二天都看不懂自己的代码，想想你的代码审查员会是什么感受吧。

现在是你改正这些愚蠢错误，并使其更易于阅读的机会。

小技巧：在代码审查时，试着把自己想象成团队里的其他人。使用他们常用的代码审查工具，比如差异检查器，并尝试检查他们经常指出的问题。例如，我的一个团队成员非常注重测试代码块的措辞，所以当我假装成他时，我会首先检查这部分。我惊讶地发现，自己能从中发现很多东西。

编写能够自我解释的代码

你的代码应该编写得简洁明了，让代码审查人员无需问你“这个函数是做什么的？”之类的问题。

即使你能在有人在 PR 中提问后解释该函数的作用，但当有人需要在没有 PR 上下文的情况下理解该函数时该怎么办？

因此，如果你的代码难以理解，就需要重写。至少，代码中需要添加注释进行解释。

如果你不确定如何以易于理解的方式编写函数，或者无法用注释简洁地解释，那么在你的 PR 中直接评论说明是可以的。PR 是用来引发讨论的地方，其目标是为所有相关方带来最佳结果。

如果你打算这样做，请务必解释清楚你尝试过哪些方法，以及最终为什么选择这种方法。这样可以方便审阅者给你提供更好的指导，然后你就可以按照他们的建议去做了。

准备一份变更清单

变更列表是一种简单的方式，可以让你向审阅者传达你所做的更改，并向他们提供他们需要的任何背景信息。

编写变更列表时，要尽量考虑未来。想象一下，两年后你需要更新代码库的这部分内容。未来的读者应该能够理解变更的背景。

我的导师说，“一份好的变更清单应该解释清楚变更的内容和原因”。“内容”指的是这项变更能达到什么目的，“原因”指的是你为什么要进行这项变更。清单还应该具体列出变更了哪些内容。

使用屏幕截图和视频也能极大地改进你的变更列表。毕竟，一张图片胜过千言万语。

为了节省审阅者的时间，请向他们展示任何视觉更改前后的对比图片，并展示不同屏幕尺寸下的显示效果。使用视频演示应用程序的新功能。帮助他们更好地帮助您。

最后，请在变更列表中添加任何相关链接，以下是一些有用的链接。

• 设计文件链接
• 链接到卡片之外的任何讨论，例如与设计师在 Slack 上进行的讨论，讨论内容包括同意任何更改。
• 票务链接
• 链接到任何相关的ADR

保持在范围内

范围蔓延是公关稿的死敌。

我指的是那些你注意到的小的用户界面问题，你觉得我可以很快解决。但实际上，这些小小的用户界面改动反而让审核流程变得混乱，审核人员不得不花费精力去思考他们到底应该审核什么。

我知道快速修改很诱人，但这样做会改变 PR 的目的。你最好创建一个新的 issue 来修复 UI 问题，这样你的审核人员就可以单独审核他们应该审核的代码了。

范围蔓延很棘手，很难克制住不去做那些小小的改动。但是，当你的 PR 需要审核时，审核人员会感谢你的，因为他们无需在审核代码时切换上下文。

提交 PR 后如何处理？

即使是写得很好的 PR，提交之后也不会就此结束。在你点击合并按钮之前，它仍在不断完善。因此，要想写出好的 PR，你需要处理好自己的工作，直到你点击合并按钮并关闭 PR 为止。

收起你的自负吧。

不要把反馈当成针对你个人的攻击。你的代码并不代表你。接受反馈时，你需要保持宽容大度。不要生气，也不要把它当成人身攻击（即使它确实是）。归根结底，你能掌控的只有一件事：你自己以及你的回应方式。你无法控制其他人会如何看待你的 PR。

如果反馈不够清晰，请放下架子，礼貌地请求对方解释清楚。你可以这样说：“你说得对，我大概明白了。请你再详细解释一下关于X的部分。” 说到底，对方只是想帮你改进代码（当然，开发者们在这方面各有千秋！）。

反馈往往是一份礼物。当审阅者发现代码中一些不易察觉的问题时，这无疑是件好事。为什么呢？因为这表明你提交的 PR 水平很高。当审阅者能够忽略那些显而易见的问题时，他们就能把时间花在逻辑、设计和边界情况等真正重要的问题上，从而获得你真正想要的反馈。

务必对审阅者好心提供的任何建议表示感激。如果他们花时间教导你，请务必以表达谢意的方式回应。

快速重构

德雷克在歌曲《One Dance》中有一句歌词——“看到短信就回复我”。我喜欢把它改成这样唱给自己听：“看到反馈就修改我”。

向审稿人表达你尊重他们时间的最佳方式就是高效响应。你可以通过快速处理他们的反馈来实现这一点。

为什么这很重要？因为这可以减少代码审阅者重新熟悉你的代码的需要。

换位思考一下。如果你审核了他们的 PR，提供了反馈，但几天后才收到他们的回复，你很可能已经忘记了他们写的代码是做什么的，以及你当初为什么给出反馈。所以你实际上需要对代码进行二次审核。

快速响应可以减少审阅者再次查看代码的需要，这意味着他们只需专注于您重构的代码即可。

但有一点需要注意，有时你需要留出足够的时间让其他人审查代码。如果对反馈意见有异议，你肯定不想一直重构代码。

我的做法是，在对代码进行任何修改之前，确保至少有两位审阅者提供反馈。一旦至少有两位开发人员审阅了代码，我就会迅速进行必要的修改，以确保 PR 能够顺利推进。

这需要根据具体情况判断，也取决于你们团队的运作方式。一般来说，如果反馈和重构之间的时间间隔超过 24 小时，就会给审核人员增加工作难度。

沟通变化

随着我阅读的优秀 PR 越来越多，我注意到在进行更改时存在一种更高效的沟通模式。这种模式是在更改完成后明确告知更改的位置，并说明更改已准备好进行下一轮审查。

这比直接推送更改并期待评审员再次介入要好得多，因为它消除了很多不确定性。评审员无需猜测你的更改是否已完成，以及是否可以进行下一轮评审。因此，你真正地尊重了评审员的时间，帮助他们避免重复评审未完成的代码。

这样也能节省审阅者的时间，因为他们不必费力查找更改的位置，只需点击您的链接即可直接审阅该部分代码。

此外，一旦反馈问题得到解决，请务必将其标记为已解决。这样，所有人都知道无需再对此问题进行深入探讨，审核人员即可批准代码，您也可以将其合并。

最后，务必通过公开渠道告知公众，您已做出修改，并且公关稿已准备好接受新一轮的审核。

别再揉搓了。

你会从资深同事身上学到很多东西。同时，你也需要明白，他们也会犯错，就像你自己也会写出错误的代码，需要修正一样。在这种情况下，你需要培养判断力、理解力和说服力，才能妥善应对。

面对审稿人的错误，想要做出反应是很正常的，尤其是在你的PR被批得体无完肤之后。我感同身受，那种感觉就像被针对了一样。但是，不要把这些错误看作是对你个人的冒犯。

关键是你要保持风度（别做混蛋）。事实上，这是个重新审视代码的好机会。如果审查者感到困惑，或许你的代码不够清晰。借此机会改进代码，或者留下解释性的注释。

结论

写出好的 PR 很难，尤其是对于新手来说。当你准备写下一个 PR 时，记住你能控制的事情，无需急于完成工作就提交 PR。

首先，用全新的视角审视代码，对照检查清单，在浪费审阅者的时间之前，务必处理所有粗心大意的错误。删除任何超出范围的内容，并留待以后处理。接下来，检查代码是否能够自我解释，如果PR中没有说明，请进行检查。最后，编写一份清晰明了的变更列表，阐明变更的内容和原因。

提交 PR 后，你的工作并没有结束，你需要及时处理所有反馈，并明确地进行沟通。如果你能遵循以上步骤，就能写出让审阅者眼前一亮的高质量 PR。

想了解更多内容？ 请在推特上关注我，获取诸如“提升开发者作品集的 5 种方法”之类的内容。