心學禪宗

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為團隊創建拉動請求提醒的工具。 如果你想摹香港專業教育學院一試。期待您的反饋意見。