心学 禅宗_禅宗宣言，用于有效的代码审查

心学 禅宗

by Jean-Charles Fabre

通过让·查尔斯·法布尔(Jean-Charles Fabre)

禅宗宣言，用于有效的代码审查 (A zen manifesto for effective code reviews)

When you are coding, interruptions really suck.

当您编码时，中断确实很糟糕。

You are in the zone, flying high, killing it. And BAM… meeting, standup, *insert interruption*… Great!

您在区域内，高高飞扬，将其杀死。 和BAM ...会议，站立，*插入中断* ...太棒了！

In that context, code reviews can be perceived as another hurdle to productivity.

在这种情况下，代码审查可以看作是提高生产力的另一个障碍。

And frankly I can relate to that.

坦率地说，我可以与此相关。

代码审查很难。 (Code reviews are hard.)

Not only do you need to stop what you are currently doing, you also need to immerse yourself into somebody else’s code. It takes a lot of energy just to switch your focus.

您不仅需要停止当前正在做的事情，还需要使自己沉浸在其他人的代码中。 仅切换焦点就需要大量精力。

代码审查非常耗时。 (Code reviews are time consuming.)

According to Slack Overflow’s 2019 survey, 56.4% of developers spend 4 hours or more per week performing code reviews. And it can represent up to 20% of a developer’s week!

根据Slack Overflow的2019年调查显示 ，有56.4％的开发人员每周花费4个小时或更长时间来执行代码审查。 它最多可以代表开发人员一周的20％！

代码审查令人沮丧。 (Code reviews are frustrating.)

As a submitter, it can be frustrating to get your pull request rejected, to wait hours if not days for a review. As a reviewer, code reviews can feel like an obstacle to a good productive day.

作为提交者，拒绝您的请求请求，等待数小时甚至数天的审核可能会令人沮丧。 作为一名审阅者，代码审阅可能像是阻碍高效工作的障碍。

Yes, code reviews can sometimes be hard, time consuming and frustrating.

是的，代码审查有时会很困难，耗时且令人沮丧。

But they’re also a good way to share knowledge, prevent bugs, and reinforce your company’s culture among other things.

但是，它们也是共享知识，防止错误以及增强公司文化的好方法。

What follows is a manifesto for submitters and reviewers to bring back peace of mind into code reviews. ?

接下来的内容是供提交者和审阅者使用的宣言，使代码审阅放心。 ？

提交人的宣言 (A Submitter’s Manifesto)

As a submitter, here’s what you can do to increase your chances of getting your pull requests approved in a timely manner.

作为提交者，可以采取以下措施来增加及时批准您的请求的机会。

完成后提交。 (Submit when you’re done.)

It sounds obvious, I know. But the thing is — most of the time if the machine doesn’t work, it’s not because it’s broken… it’s because it’s not plugged in!

听起来很明显，我知道。 但问题是-大多数情况下，如果机器无法正常工作，并不是因为机器坏了……而是因为没有插入电源！

Very small details can make a big difference on how your work is perceived. And you don’t want your colleagues to feel they are investing time and effort into reviewing work in progress code.

很小的细节可以对您的工作产生很大的影响。 而且，您不希望您的同事感觉到他们正在花时间和精力来审查正在进行的代码。

Me: “It was just a missing </div>!”

我：“那只是失踪</ div>！”

You: “Yeah I know, but the whole thing didn’t work and it took me 20 minutes to spot it.”

您：“是的，我知道，但是整个过程都没用，我花了20分钟才发现它。”

So here’s what you can do:

因此，您可以执行以下操作：

• Self-test your code. Include WIP in title or label if you’re not done yet.

  自测试您的代码。 如果尚未完成，请在标题或标签中包含WIP。

• Self-review your code. Use the diff report of your code editor or versioning tool to catch mistakes.

  自检您的代码。 使用代码编辑器或版本控制工具的差异报告来发现错误。

• Make sure the tests of your CI are green before assigning a reviewer, this will save them time.

  在分配审阅者之前，请确保您CI的测试为绿色 ，这样可以节省时间。

提出较小的拉取请求 (Make smaller pull requests)

I get it, it’s a big, important and complex feature and you might be tempted to submit a long pull request. Yet, most of the time, you are better off submitting smaller pull requests.

我明白了，它是一个很大，重要且复杂的功能，您可能很想提交一个长请求请求。 但是，大多数情况下，最好提交较小的拉取请求。

Code reviews take energy. Big code reviews even more. Don’t impose on your team a developer vs food challenge every time they review your code.

代码审查需要精力。 大代码审查甚至更多。 不要在每次审核您的代码时都向您的团队施加开发人员与食品方面的挑战。

Be nice, cut it in smaller chunks. You are also doing yourself a favor:

很好，切成小块。 您也正在帮自己一个忙：

• You’ll get more qualitative feedback. The longer a pull requests the fewer qualitative feedback per line of code you’ll receive. Keep your pull request small (not too small either) and you’ll increase your chances of getting great feedback on it.

  您将获得更多的定性反馈。 拉取时间越长，您将收到的每行代码的定性反馈越少。 保持拉取请求较小(也不要太小)，您将增加获得大量反馈的机会。

• You’ll get them approved faster. It’s a win-win, by breaking down your work into smaller pull requests, you increase your chances of getting them approved faster.

  您会更快地批准它们。 通过将您的工作分解为更小的请求，这是双赢的，您增加了更快地批准它们的机会。

For the nerds out there, here’s a study conducted on a Cisco programming team. It shows that after 400 LoC the ability to find defects diminishes pretty dramatically. ?

对于在那里的书呆子，这是对思科编程团队进行的一项研究 。 它表明，在400 LoC之后，发现缺陷的能力会大大降低。 ？

The next principle helps with keeping pull requests size under control.

下一条原则有助于控制拉取请求的大小。

缩小范围 (Narrow the scope)

The scope of your pull request should be simple, unique and well-defined. That might be a feature, a user-story or a bug fix.

拉取请求的范围应简单，唯一且定义明确。 这可能是功能，用户故事或错误修复。

One way to think about it is that reviewers have a limited number of “attention credits” (like everybody). Every time they focus on something, they use 1 credit. What happens when they have 0 left?

一种考虑方式是，审阅者的“注意力积分”数量有限 (就像每个人一样)。 每当他们专注于某件事时，就会使用1个学分。 当他们剩下0时会怎样？

LGTM ?

LGTM？

Do what you can to reduce the noise around your work. Be mindful of the reviewer’s attention span.

尽力减少工作中的噪音。 注意审阅者的注意力范围。

For instance, avoid void changes (like skipping lines). They don’t add any value and complicate the code review.

例如， 避免空白更改 (例如跳过行)。 它们不会增加任何价值，也不会使代码审查复杂化。

Similarly, if your pull request changes the behavior, don’t include changes to formatting. Conversely, if your pull request changes formatting, don’t include changes that affect the behavior. They might be overlooked by the reviewer.

同样，如果您的拉取请求更改了行为 ，请不要包括对formatting的更改。 相反，如果您的拉取请求更改了格式 ，请不要包括影响行为的更改。 他们可能会被审阅者忽略。

提供背景 (Give context)

Think about your pull request as documentation for new comers. Guide the reader with context.

考虑将您的拉取请求作为新手的文档。 用上下文指导读者。

Start with a self-explanatory title.

从不言自明的标题开始。

Then, write a clear description to explain what you are doing and why are you doing it. What is the purpose of this pull request? Why is this change necessary? How did you approach this problem?

然后，写一个清晰的说明来解释您在做什么以及为什么这么做。 该请求请求的目的是什么？ 为什么需要进行此更改？ 您是如何解决这个问题的？

The description is also is great place to point out unresolved issues and open questions. Reviewers might have suggestions to unblock you.

该说明也是指出未解决问题和未解决问题的好地方。 评论者可能会建议您解除封锁。

Are you working on a visible part of the product? Screenshots can help get your point across faster.

您是否正在处理产品的可见部分？ 屏幕截图可以帮助您更快地理解观点。

• Show before/after differences.
  显示差异前后。
• Use colored arrows.
  使用彩色的箭头。
• Add screen recordings if you feel like it :)
  如果您愿意，可以添加屏幕录像:)

Finally, write information signs along the way to guide the reviewer through your reasoning.

最后，一路写下信息标志 ，以指导审阅者进行推理。

Keep a clean commit history to make it easier for the reviewer to follow your step. Use comments to point out alternatives you explored.

保持干净的提交历史 以便审核者更轻松地遵循您的步骤。 使用注释指出您探索的替代方法。

欢迎反馈？ (Welcome feedback ?)

Rejection hurts.

拒绝很痛。

Truth be told, code rejection hurts even more.

实话实说， 拒绝代码的痛苦更大。

It’s alright. Don’t take it personally.

没关系。 不要个人考虑。

Comments and suggestions are an opportunity to learn and become a better software engineer ?

意见和建议是学习并成为更好的软件工程师的机会吗？

审稿人宣言 (A Reviewer’s Manifesto)

Congrats on making it this far! Now let’s look at a few principles that might help you become a better reviewer ?

恭喜！ 现在，让我们看看一些可以帮助您成为更好的审稿人的原则？

采取正确的心态 (Adopt the right mindset)

There is no scenario where a team can benefit from a reviewer being mean or patronising. Be kind. Period.

在任何情况下，团队都不会因为评审员的刻薄或光顾而受益。 善待 。 期。

Want to make code reviews more exciting?

想要使代码审查更令人兴奋吗？

Look for something you can learn from this review. A new library, a new method, a new concept, a simpler way to do things. What piece of knowledge will you extract from it?

寻找可以从此评论中学到的东西。 新的库，新的方法，新的概念，更简单的处理方式。 您将从中提取什么知识？

If you are the more experienced developer, is there something you can share? How can you use this review to transfer knowledge to the submitter? How can you help them become a better software engineer?

如果您是经验更丰富的开发人员，可以分享一些东西吗？ 您如何使用此评论将知识传递给提交者？ 您如何帮助他们成为更好的软件工程师？

如何实际进行代码审查 (How to actually do a code review)

评论什么 (What to review)

What am I even supposed to look for? Without clear guidance on what and how to review, it’s easy to get lost. Here is what you can do.

我什至应该寻找什么？ 如果没有关于如何审核的明确指导，很容易迷路。 这是您可以做的。

First off, check the purpose. Is this code accomplishing what it is meant to do? Are there parts of the new code that are not clear to you? Ask clarifying questions. The code is easily testable? Test it. There’s no need to go beyond if this square is not checked.

首先， 检查目的 。 这段代码完成了它的意图吗？ 新代码中是否有您不清楚的部分？ 提出澄清的问题。 该代码很容易测试？ 测试一下。 如果未选中此正方形，则无需超出范围。

Ok now that the code works, time to focus on the implementation.

现在代码可以正常工作了，现在可以专注于实现了 。

Think about how you would have approached this problem. Would you have done it differently? Is there potential for refactoring or abstraction? Is this re-inventing the wheel? Is this using standard code patterns?

考虑一下您将如何解决此问题。 您会做不同的事情吗？ 有重构或抽象的潜力吗？ 这是在重新发明轮子吗？ 这是使用标准代码模式吗？

什么不复习 (What to not review)

Because a piece of code has room for improvement, it doesn’t always mean it needs to be improved.

因为一段代码有改进的余地，所以它并不总是意味着需要进行改进。

At the end of the day, code reviews are a tradeoff between quality and velocity and depending on the scope and stage of the project it might make sense to let a few things behind.

归根结底，代码审查是质量和速度之间的权衡，根据项目的范围和阶段，可能需要注意一些事情。

Similarly, you shouldn’t be doing things that can be automated. Let your favorite linter hunt for the missing semicolons and extra indentation. No need for an endless debate on tabs vs spaces.

同样，您不应该做可以自动化的事情。 让您最喜欢的短毛猫寻找缺少的分号和额外的缩进。 无需对制表符和空格进行无休止的辩论。

Finally, don’t increase the scope of the pull request. If you think of new things that need to be done, create a new pull request /task for that matter.

最后，不要增加拉取请求的范围。 如果您想到了需要做的新事情， 为此创建一个新的拉取请求/任务。

及时审查 (Review in a timely manner)

There are at least 3 good reasons to review pull requests in hours rather than days.

至少有3个很好的理由可以在数小时而不是数天内审查请求请求。

• The submitter can move to the next task quicker
  提交者可以更快地移至下一个任务
• It reduces context switching cost
  它减少了上下文切换成本
• It reduces the risk of merge conflicts between branches.
  它降低了分支之间合并冲突的风险。

Disclaimer: I just released GitRise, a tool that helps teams using GitHub & Slack review pull requests faster. I do think it can help with this one :)

免责声明：我刚刚发布了GitRise ，该工具可帮助使用GitHub＆Slack审核的团队更快地提取请求。 我确实认为它可以帮助解决这个问题:)

如何在代码审查中提供反馈？ (How to give feedback in a code review?)

When giving a feedback, the form matters as much as the substance.

在提供反馈时，形式与实质同样重要。

Did you know that in written communication, neutral content looks more negative than it actually is? Beware of this bias and include emojis when needed to get the tone right in your comments.

您是否知道，在书面交流中， 中性内容看起来比实际情况更负面吗？ 当心这种偏见，并在需要时添加表情符号以使您的评论中的语气正确。

Also, most of the time, even if you are pretty sure that there is a better way to do something, you are better off asking a question rather than requesting a change. Plus, questions sound less aggressive.

同样，在大多数时候，即使您非常确定有更好的方法来做某事，也最好还是问一个问题而不是请求更改 。 另外，问题听起来没那么积极。

Finally, reward when things are done right. Code reviews are also a great place to give kudos to colleagues for doing a good job. Be creative and fun :)

最后，当事情做对了时奖励。 代码审查也是赞扬同事出色工作的好地方。 有创造力和乐趣：)

? Congrats on reaching the end of this blog post!

？ 恭喜您完成本博文的结尾！

? Thanks a lot for reading and let me know if you have any comments!

？ 非常感谢您的阅读，如果您有任何意见，请通知我！

? I just released GitRise, a tool that creates pull requests reminders for teams using Slack & GitHub. Give it a try if you want. Looking forward to your feedback.

？ 我刚刚发布了G itRise，它是一个使用Slack和GitHub为团队创建拉动请求提醒的工具。 如果你想摹香港专业教育学院一试。 期待您的反馈意见。

翻译自: https://www.freecodecamp.org/news/a-zen-manifesto-for-effective-code-reviews-e30b5c95204a/

心学 禅宗