Code Review 礼节

Code Review 礼节
0

原文:https://css-tricks.com/code-review-etiquette/

Code review 在软件开发中(尤其是团队协作开发)非常重要,团队内部有必要对于 code review 礼节达成统一意见。Code review 本质是一种分析点评,而分析点评相对于写代码本身更加主观。草率、研究不充分或不到位的分析会给团队成员之间的沟通造成困难,降低团队整体工作效率,时间长了还会降低代码质量。这篇文章将简要定义 code review,阐述 code review 过程中常见的错误,并提供改进 code review 的实用技巧。

什么是 code review?

Code review 是将代码公开给其他工程师审查的过程。Code review 可以在结对编程期间口头进行,也可以在 CodePenGitHub 等网站上进行。大部分情况下,工程师通过在 GitHub 这类工具中提交 pull requests 进行 code review。

对代码进行分析点评极为有益。可以召集工程师们当面交流或者(远程)协作对代码进行讨论,以确保他们的节奏一致。此外,code review 可以帮助我们发现代码或注释中的小错误,比如拼写错误,还可以帮助萌新或初级程序员学习代码库。如果做得好,定期的 code review 对所有参与者来说都有好处。

Code review 需要代码变更尽可能小和清晰,以便审阅者可以轻松了解代码中有哪些更改以及做了什么。如果 code review 的内容足够少,则可以更频繁地进行,可能每天几次,而且更易于管理。

Code review 应是每个开发者工作流程的一部分。在 code review 过程中,高级工程师可以进行教学、指导,甚至自己不时学习一些新东西,而初级工程师可以得到成长,并且他们提出的问题可以帮助确保代码的可读性。事实上,初级工程师通常是团队中确保代码可读性的最佳成员。

对独立开发者来说,当遇到人们在线下活动、GitHub、Slack 开源频道、Reddit、Twitter 等场合展示代码并向外界寻求反馈时,他们就有机会参与 code review 过程。

如果我们对 code review 的流程和使用的语言达成一致,那么我们就更容易维持一个富有创造力和高工作效率的积极环境。不管是对独立开发者还是团队,Code review 礼节对所有人都有好处。

苛刻的 code review 会降低士气

每当我遇到 bug,或者问题不断出现并且无法解决时,常会有挫败感和沮丧感。对待正在进行的项目,我只看到那些消极的因素,只想着自己曾经碰到过的 bug、用词不当和犯过的错。这就让我进入了一个恶性循环,因为过于沮丧而无法继续工作,由于不工作而更加沮丧。 - Tim Wood,Momentjs 作者

网上有很多工程师发表评论、帖子和推文说 code review 伤害了他们。并不一定是说那些评论者故意要这么刻薄,对负面批评反馈产生自我防御是人类本能的反应。评论者应该意识到审核意见的语调、语气或情绪会影响被评论者对评价原文的理解。— 参考奥卡姆剃刀原理

“这些评论的人以为我们这些维护人员好象不是人,不会犯错误。” — Henry Zhu @SF (@left_pad) September 18, 2017

虽然 code review 有很多好处,但糟糕或草率的 code review 可能会产生相反的结果。避免只批评而不提供背景。换句话说,就是花些时间解释为什么出了问题,哪出了问题,以及如何解决问题。体现出对被评审者的尊重可以加强团队凝聚力,提高工程意识,并有助于统一对技术定义的理解。

快速改善 code review 的几个建议

代码编写的本质就是要符合逻辑,找出不正确或可以改进的代码就像找到拼写错误一样简单。对待或讨论某些逻辑事例(如代码)时,容易忽视他人感受,这是人们的通病。这会造成在感情上伤害到他人,使他们无法专注学习和合作。

由于人们的这种通病,提升 code review 素养是有困难的。下面列出我曾做过、说过、看过或收到的注意事项,这些都是 code review 礼节中很容易把握的小技巧。

对事不对人

由于交流沟通中的各种人际关系,工程师们会忽视有见解的专业点评和单纯的指责两者之间存在区别。

下面剖析了一个函数的 code review 意见,建议有机会尽早 return 这个函数。

你或我: 使用不会让人觉得有意冒犯。但是,久而久之,涉及到的“你”会开始感觉不自在,尤其是在语音评述时。

你应该尽早 return 函数

我们:我们比较包容,是一个比较安全、可以更直接地表达想法的方式,而且不会让人感到被冒犯。然而,如果是个未参与编写代码的外人用我们,这种包容听上去就有点作假,有点麻木。

我们应该尽早 return 函数

不使用人称指代: 没有人称指代,谈话或点评只密切针对谈论的问题、想法或 issue。

尽早 return 函数

可以看到,不用人称代词谈论同一件事用的文字更少,更清晰。将代码讨论和个人间讨论区分开,表达相同的想法需要的文字更少,也更有助于人与人之间的互动。

将富有激情的点评平和地表达出来

激情是改进的重要动力。富有激情的点评是非常重要的,可以表达对被点评者的体谅与鼓励。只有相关的人员收到技术评论,反馈才是最有用的。在讨论架构或新产品时的交流通常就是这样的。

只有相关的人员收到技术评论,反馈才是最有用的。注意: 在点评的时候让被点评者参与进来。

想象一下用夸张的肢体语言、激动的声调、大声地说这句话。

本次模拟中使用了 8 种网络字体,这可能会影响页面加载速度,或者其他潜在因素可能影响其他指标!

然后,想象一个类似的点评效果,语气更温和,更简洁,以平静、缓慢、正常的声音表达,最后再提一个问题。

本次模拟中使用了 8 种网络字体。由于潜在的竞争条件,这将影响页面加载速度和其它指标。如何改善这种情况?

请注意上面的点评几乎表达同一个意思。但第二个点评更直接。它把问题陈述为事实,然后询问反馈。

当满怀热情时,记得保持语气平和。这种平和是通过身体语言而不是社交语言展示出来的。基于交流者的语气,语言表达的意思可以是相同的,也可以是截然不同的。如果身体语调(肢体语言)、声调、音高和音量保持温和,听话的人更有可能保持交流——即使评论本身批评性较强。

如果语气具有攻击性(夸张的身体运动、更激动的声调、更高的音量),即使用的词语原本是温和的,听话的人也会有非常不同的感受。这样交流可能会导致双方尴尬、听话的对方不回应,甚至失去尊重。

激情交流中说话气势汹汹很常见,因为人们本能偏向于维护自己充满激情的想法。所以,如果发现你的听众在讨论你感兴趣的事情时不感兴趣,不用太担心。关键是要记住,如果你能创造出可感知的温和交流环境,即使他们最初的想法与你不一致,也会更容易保持和你积极交流。

只评议代码,不对作者说三道四

通过上面的讨论,不论在书面对话或实际肢体语言中,论语境本身转移到某个人或某件事都不是良好沟通的最佳方式

以下的回复提供了评论。在 code review 本身的语境中,注释的第二句偏离了 code review 的内容本身,这会令人非常困惑。

// 提前在函数中 return
// 你需要学习函数式编程

下面的评论提供了一个注释,以及伪代码建议。.

/*
  像这样提前 return:
*/
const calculateStuff = (stuff) => {
  if (noStuff) return
  // calculate stuff
  return calculatedStuff
}

在上面的两个例子中,第一个例子让读者偏离了问题本身,很抽象。第二个示例直接引用问题,然后提供一个与内容相关的伪代码片段。

Code review 时,最好只对特定的上下文进行点评。宽泛的点评会丧失语境。如果必须进行更广泛的点评,应该在 code review 之外进行。这样就可以保持清楚地只评论代码,并将范围限定在被评述的代码编程上。

对错是可变的

开发者总是想重构。为了解决当下的问题很自然地将问题实时分解成任务。然而,关注产品历史的“人”和“为什么”,同样对于理解产品概念很重要,因为可以从中得知历史背景。当你在点评别人的产品或者你的产品被点评时,要记住“历史总会重演”。从历史背景中总能获得大量的信息。

JavaScript 是在一周内写成的,当时被认为是一种黑客脚本语言,后来却成为世界上使用最广泛的编程语言。早在 1999 年就已经支持可缩放矢量图形(SVGs) 了,几乎要被遗忘了,而现在,它因提供的新可能性而广受欢迎。甚至万维网(互联网)当初只是为了文档共享而设计的,谁也没有预想到会有今天的结果。当考虑软件和工程时,所有这些技术都很重要——成功往往来自意想不到的结果,请怀抱开放的态度!

有助于提升 code review 礼节的资源和工具

结论

以上罗列了有助于积极参与讨论、评议或阅读代码初阶、高阶的 code review 礼节。

在这篇文章中我建议不要犯的错误我都犯过。我不虚伪,是人都会犯错。我的目标是帮助其他人避免再犯我曾经犯过的错,也许鼓励在 code review 时遵循一些行为标准,这样工程师就可以更公开地讨论代码,而不用担心伤害到其他人。

3赞

Code reviews are a big part of writing software, especially when working within a team. It is important to have an agreed-upon etiquette for reviewing code within a team. A code review is a critique and a critique can often feel more personal than the code writing itself. A sloppy, under-researched, or insensitive code critique can cause difficulties between team members, reduce overall team productivity, and diminish code quality over time.

Code review 在软件开发中(尤其是团队协作开发)非常重要,团队内部有必要对于 code review 礼节达成统一意见。Code review 本质是一种分析点评,而分析点评相对于写代码本身更加主观。草率、研究不充分或不到位的分析会给团队成员之间的沟通造成困难,降低团队整体工作效率,时间长了还会降低代码质量。

Mainly, code reviews happen in tools like GitHub when engineers submit pull requests.

大部分情况下,工程师通过在 GitHub 这类工具中提交 pull requests 进行 code review。

Critiques are hugely beneficial. Convening engineers to discussions about code ensure that they’re on the same page, regardless of whether it’s in person or by sharing comments.

对代码进行分析点评极为有益。可以召集工程师们当面交流或者(远程)协作对代码进行讨论,以确保他们的节奏一致。

Senior reviewers are given the opportunity to teach/mentor, and even learn something new from time to time. Junior reviewers can grow and often help ensure code readability through the questions they ask. In fact, junior engineers are usually the best team members to ensure code readability.

在 code review 过程中,高级工程师可以进行教学、指导,甚至自己不时学习一些新东西,而初级工程师可以得到成长,并且他们提出的问题可以帮助确保代码的可读性。事实上,初级工程师通常是团队中确保代码可读性的最佳成员。

For an engineer who works alone, asking for feedback from outsiders — at meet-ups, GitHub, Open Source Slack Channels, Reddit, Twitter, etc — can allow the solo coder the opportunity to participate in a code review process.

对独立开发者来说,当遇到人们在线下活动、GitHub、Slack 开源频道、Reddit、Twitter 等场合展示代码并向外界寻求反馈时,他们就有机会参与 code review 过程。

If we could all agree on an established process and language for reviewing code, then maintaining a positive environment for creative and productive engineering is easier.

如果我们对 code review 的流程和使用的语言达成一致,那么我们就更容易维持一个富有创造力和高工作效率的积极环境。

以上已经修改到正文,谢谢miya专业的校对

其实你的翻译已经很清楚了,我就是结合咱们中国人的阅读习惯做一些语义上的调整,你要是觉得我的校对有不够好的,也可以提出来讨论 :grinning:

我明天应该可以校对完。

Seeing bugs and issues continue to roll in and being mentally unable to address them has led to feelings of failure and depression. When looking at the moment project, I could only see the negatives. The bugs and misnomers and mistakes I had made. It led to a cycle of being too depressed to contribute, which led to being depressed because I wasn’t contributing.
Tim Wood, creator of Momentjs

看到层出不穷的 bug 和 issue,而我无法解决它们,这让我有一种挫败感和沮丧感。我只看到人们对 Moment.js 项目的否定,只看到我写过的 bug,用错的字眼和犯过的错误——这就导致一个恶性循环:我因为过于沮丧而无法继续工作,又因为没有工作而感到更加沮丧。——Tim Wood,Momentjs 作者

There are many online comments, posts, and tweets by prolific engineers expressing that their feelings have been hurt by code reviews. This doesn’t directly mean that reviewers are trying to be mean. Feeling defensive is a normal, quite human reaction to a critique or feedback. A reviewer should be aware of how the pitch, tone, or sentiment of their comments could be interpreted but the reviewee — see Occam’s Razor.

很多贡献卓著的工程师在线发表评论、帖子和推文说 code review 伤害了他们。这并不一定是说审核者故意要这么刻薄,因为对负面批评反馈产生自我防御是人类本能的反应。所以审核者应该意识到审核意见的语调、语气或情绪都会引起被审核者怎样的解读。——参考奥卡姆剃刀原理

that are easy wins in the art of Code Review Etiquette.

这些都是 code review 礼节中很容易把握的小技巧。

#Remove the person

Without realizing it, engineers can neglect the difference between insightful critique and criticism because of personal relationships in communication.

避免使用单数人称

在沟通中对人称的使用,是区别有见解的专业点评和单纯的指责的因素,工程师们可能没有意识到自己忽视了这个因素。

Remove the person

Without realizing it, engineers can neglect the difference between insightful critique and criticism because of personal relationships in communication.

The lines below dissect a code review comment of a theoretical function where it is suggested that there is an opportunity to return out of the function early.

将富有激情的点评平和地表达出来

激情是促使人改进的重要动力。富有激情的点评是非常重要的,可以表达对被点评者的体谅与鼓励。而让被点评者参与进来给出反馈也很有用。在讨论架构或新产品时的交流通常就是这样的。

让被点评者参与进来给出反馈也很有用。 注意: 在点评的时候让被点评者参与进来。

An important thing to remember when being passionate is taking on a quieter tone. This is a physical decision — not a social one. Passionate language can be the same, and perceived very differently, based on the orientation of the communicator’s tone. If physical tone (body language), vocal tone, vocal pitch, and vocal volume remain gentle, it is observed that it is much more likely for an audience to remain engaged — even if the critique is critical in nature.

当满怀热情时,记得保持语气平和。这种平和是通过身体语言而不是社交语言展示出来的。即便语言本身富有激情,但是通过温和的身体语言、声音、语调和音量表达出来,给人的感觉也是截然不同的,可以让观众参与进来——即使点评本身的批评性较强。

Following the conversation above, the act of pointing, within written conversation or actual body language, in almost any situation is not optimal for good communication. It changes the focal point of the conversation from the context of the conversation to a person or a thing.

通过上面的探讨我们可以看出,不论是在书面对话还是在实际肢体语言交流中,有指代性的行为对于良好沟通来说都是不好的,它将对话的焦点从对话的上下文转移到某个人或某件事。

‘History repeats itself’ is an important phrase to remember when critiquing products or when a product you’ve written is critiqued.

当你在点评别人的产品或者你的产品被点评时,要记住“历史总会重演”。

谢谢miya,译文已经根据你的意见做了部分调整。辛苦了:smiling_face_with_three_hearts:

最终发布的文章:《Code Review 礼节》