很好的代码笔记_什么使一个好的代码检查工具很好

很好的代码笔记

Most tech companies have a blocking, required code review step in their engineering processes. This means that as a software engineer working for one of these companies, the code you write has to be reviewed and approved by another software engineer. Some companies might even enforce that at least two other peers review and approve your code. This creates attrition in the engineering process among the engineers: if someone left a comment questioning something you're doing on your change, you either have to change the code you wrote or convince the other people that the way you wrote it is how it should be. A comment might be a suggestion, a question, a challenge. Irrespective of the tone or content of the comment, if you receive a comment on your review, you have to reply to it and it might entail a — hopefully not long — discussion.

大多数科技公司在其工程流程中都有阻塞性的，要求进行代码审查的步骤。 这意味着，作为在其中一家公司中工作的软件工程师，您编写的代码必须由另一位软件工程师进行审查和批准。 一些公司甚至可能强制至少另外两个同行审查并批准您的代码。 这在工程师之间的工程过程中造成了消耗：如果有人留下评论质疑您所做的更改，那么您要么必须更改您编写的代码，要么使其他人相信您的编写方式是应该的是。 评论可能是建议，问题或挑战。 无论评论的语调或内容如何，​​如果您收到对评论的评论，都必须回复它，这可能需要进行(希望不长)的讨论。

A code review should be a collaboration tool where reviewers help raise the quality of the code the author produced by leaving suggestions or questions in the form of comments. It should never feel like a battle of opinions or tenures, and the tool should assist in this too.

代码审查应该是一种协作工具，审查者可以通过以注释的形式留下建议或问题来帮助提高作者编写的代码的质量。 它永远不应该感觉像是一场观点或任期之战，并且该工具也应该为此提供帮助。

As a rule of thumb, if you force your software engineers to spend time on some sort of collaboration tool, they are bound to spend a lot of time in it. They will not just be the authors in the code reviews, but also reviewers, leaving comments themselves. So if your software engineers are going to spend a lot of time in a code reviewing tool, why not invest in a really good one? After all, the better the tool, the more productive the engineers. But what really makes a good code reviewing tool? I am going to list a few things based on my experience with both what I would consider good and terrible code reviewing tools. For this, I am going to wear the product manager hat and imagine that I am designing the best code reviewing tool in the world that will make my customers — the engineers — both happy and productive.

根据经验，如果您强迫软件工程师将时间花在某种协作工具上，那么他们一定会在其中花费大量时间。 他们不仅将成为代码审阅的作者，而且还将成为审阅者，而自己留下评论。 因此，如果您的软件工程师要花大量时间在代码检查工具上，为什么不投资一个真正好的工具呢？ 毕竟，工具越好，工程师的生产力就越高。 但是，什么才是真正好的代码审查工具呢？ 我将根据我对良好和糟糕的代码审查工具的经验，列出一些内容。 为此，我要戴上产品经理的帽子，想象一下我正在设计世界上最好的代码审查工具，这将使我的客户(工程师)感到既高兴又高效。

即时贴 (Sticky comments)

Believe it or not, there are still code reviewing tools which are widely used in the market today which do not have sticky comments. If your fellow author of the code review decides that they want public functions above private ones after updating the code review with the latest changes, then the comment you wrote might land on a totally different line, forcing everyone who is reading the code review to go back to the specific iteration where you left the comment to make sense out of it, forever.

信不信由你，仍然有当今市场上广泛使用的，没有粘性注释的代码检查工具。 如果您的代码审阅的其他作者在用最新更改更新代码审阅后决定让他们希望公共职能高于私人职能，那么您撰写的评论可能会落在完全不同的一行上，从而迫使所有正在阅读代码审阅的人去做回到特定的迭代中， 直到永远留下注释，使注释变得有意义。

代码着色 (Code colouring)

You can't make everybody happy with their different IDE setups, but you can adopt the basic code colouring for every programming language there is. It should be pretty obvious, but colouring the code makes it easier for the engineers to review it as it reduces the cognitive load since they would already be used to the colours they see. Colour-blind friendly tones only, please.

您不能使每个人都对他们不同的IDE设置感到满意，但是您可以为每种编程语言采用基本的代码着色。 这应该很明显，但是对代码进行着色可以使工程师更轻松地对其进行审查，因为这可以减少认知负担，因为它们已经习惯了所看到的颜色。 请只使用颜色盲友好的色调。

固定的已更改文件列表 (Pinned list of changed files)

If you are looking at a web page, you don't want to have to keep scrolling back up to click on links that will take you to the next part of the story you're reading. You want the link to the next chapter to be just there, at the point of the screen that you're staring at now. Especially for code reviews, there should be a lot of back and forth between files that the author changed. As a reviewer, you want to make sure that the author wrote proper unit tests for a function that was introduced, and those should be in a separate file. Guess what? Having to scroll to find either the code of the other file or a link that takes you there is not fun. Just pin the list of files changed on the left side of the screen so that I can navigate them without scrolling, please!

如果您正在查看网页，则不需要继续向上滚动来单击链接，这些链接会将您带到您正在阅读的故事的下一部分。 您希望到下一章的链接就在您当前正在凝视的屏幕上。 特别是对于代码审查，作者更改的文件之间应该有很多来回的关系。 作为审阅者，您要确保作者为引入的功能编写了正确的单元测试，并且这些测试应该放在单独的文件中。 你猜怎么了？ 不必滚动查找其他文件的代码或将您带到那里的链接，这很有趣 。 只需将更改的文件列表固定在屏幕的左侧即可，以便我无需滚动即可浏览它们！

只需单击一下即可比较迭代 (Comparing iterations with a simple click)

When you work on big teams or big companies, you are going to review a lot of code. And I mean a lot. That means that you will forget minor details or even big details of the code you have already reviewed. When looking at a comment you left, you might wonder how the code looked like when you left it and how it was changed. You are looking for the delta between the current iteration and the last one — or any other. Seeing the iterations and comparing them should be as easy as a click. Their contents should be comparable to any other iterations so that the reviewers can clearly see what was changed or how something was solved. Also, the screen should not be refreshed or reset to the beginning of the page when they are compared because if a reviewer is looking for the differences between the current and another iteration, it's because they are interested in a very specific section they are currently looking at, not the entire code review. Refreshing the page means back to scrolling.

当您在大型团队或大公司工作时，您将要审查许多代码。 我的意思很多。 这意味着您将忘记已经查看过的代码的次要细节甚至大细节。 查看留下的评论时，您可能会想知道代码在离开时的样子以及更改方式。 您正在寻找当前迭代与最后一个迭代之间的差值。 只需单击一下，即可查看迭代并进行比较。 它们的内容应与其他任何迭代都具有可比性，以便审阅者可以清楚地看到所做的更改或解决方法。 此外，比较时，不应刷新屏幕或将其重置为页面的开头，因为如果审阅者正在寻找当前迭代与另一个迭代之间的差异，那是因为他们对当前正在寻找的特定部分感兴趣而不是整个代码审查。 刷新页面意味着返回到滚动。

可选文本供注释，而不仅仅是整行 (Selectable text for comment, not just the entire line)

Most modern code reviewing tools only allow you to comment for a specific line. A line might be too big, or might have a lot of stuff going on for it. Allowing the engineers to select a specific portion of the text instead of the whole line avoids having them pointing out specifically what they are referring too. If you find a typo in a sentence in a comment section and you can only add a comment for the whole line, you have to point out the specific word in your comment. Allowing the engineers to only select a specific word provides for a more granular review and discussions.

大多数现代代码检查工具仅允许您注释特定行。 一条线可能太大，或者可能有很多东西在进行。 允许工程师选择文本的特定部分而不是整行，可以避免让他们也明确指出他们所指的内容。 如果在注释部分的句子中发现错字，并且只能为整行添加注释，则必须在注释中指出特定的单词。 允许工程师仅选择一个特定的单词可以进行更细致的审查和讨论。

评论状态 (Statuses for comments)

A comment that a reviewer has left on your code review is essentially an open discussion that might end up in a number of different ways. More people might chime in with their opinions, it might require another engineer from another team to participate in the discussion or a product manager, but ultimately, it's not a simple binary which results in done or not done. The author might choose to not accept the suggestion because they don't agree with it, or because it's simply invalid. A suggestion might be accepted on that code review, but it might also be done as part of a subsequent change. All of this is worth representing on the tool too, which can even lead to some pretty interesting insights. For example, how often does an engineer respond with won't fix to comments their peers leave in their code review? Or how often does an engineer comment something which receives the invalid status? The resolution of the comments are never going to be binary all the time, so the engineers should be able to represent different outcomes other than just done or not done.

审阅者在您的代码审阅中留下的评论本质上是公开的讨论，可能以多种不同的方式结束。 可能会有更多的人听取他们的意见，可能需要另一个团队的另一位工程师参加讨论或产品经理，但是最终，这不是一个简单的二进制文件，它导致完成或未完成 。 作者可能会选择不接受该建议，因为他们不同意该建议，或者只是无效。 该代码审查可能会接受建议，但也可以将其作为后续更改的一部分。 所有这些都值得在工具上表示，甚至可以带来一些非常有趣的见解。 例如，工程师多久回应一次， 而他们不会修正同行在代码审查中留下的评论？ 还是工程师多久评论一次收到无效状态的东西？ 注释的分辨率永远不会一直是二进制的，因此工程师应该能够代表不同的结果，而不只是完成或未完成 。

审阅者的状态 (Statuses for reviewers)

As a reviewer, you probably don't want the author of the code to merge it before you finish reviewing it. But if the tool doesn't allow them to know you're reviewing, how can they know? Similarly to the comments, a reviewer also has a set of statuses that they can take on when reviewing code. You might be actively reviewing which means you're looking at the code. You might have queued the code review to your task list and will review it at a later point in time. You might have decided that you don't want to spend your time reviewing it and therefore the author should ask another peer to do so. You might have already left a bunch of comments and are now waiting for their resolution before taking a second go on the code review. All of the above are again complex situations that should be representable on the tool. The tool should be able to represent in real time that an engineer is actively reviewing and leaving comments too. It is very frustrating when you spend a whole lot of time reviewing something and when you press the submit button you find out that someone else approved the change and the author merged it because they didn't know you were reviewing it. Reviewing code is very much like reviewing a document, so the same principles adopted by Google Docs should be adopted here too. With Google Docs, You can see who is looking at the document in real time and their comments are also published as they are submitted, not batched. This also allows the code author to know of the progress of the reviewer in their code review.

作为审阅者，您可能不希望代码作者在完成审阅之前将其合并。 但是，如果该工具不允许他们知道您正在审核，他们怎么知道？ 与评论类似，审阅者还具有一组在审阅代码时可以采取的状态。 您可能正在积极检查，这意味着您正在查看代码。 您可能已将代码检查排队到您的任务列表中，并将在以后的时间点对其进行检查。 您可能已经决定不想花时间审查它，因此作者应该请另一个同行这样做。 您可能已经留下了一堆注释，现在正在等待它们的解决方案，然后再进行代码审查。 以上所有都是复杂的情况，应该在工具上可以表示。 该工具应能够实时表示工程师正在积极审查并留下评论。 当您花费大量时间审查某项并且按下提交按钮时，您发现其他人批准了该更改，并且作者合并了该更改，因为他们不知道您正在审阅它，这非常令人沮丧。 审阅代码非常类似于审阅文档，因此此处也应采用Google Docs采用的相同原则。 借助Google文档，您可以实时查看谁在查看文档，并且他们的评论也会在提交时(而不是批量)发布。 这也使代码作者可以知道审阅者在其代码审阅中的进度。

友好的术语 (Friendly terminology)

I am not a terminology expert, but I can figure out what choice of words might trigger a heated discussion or not. The tool is going to shape the behaviour of the engineers for good or for bad. I have worked with a tool that phrases that you're waiting for changes from the author as "requested changes" with a nice red X beside it. This is enough to make it look like it's a personal thing or as if it is imperative that the code author must accept every suggestion of the reviewer that "requested changes", when in reality, what you're really trying to say is "Hey, I left some comments and would like to see their responses before the changes get merged." When mapping the reviewer statuses, they should be called and represented in the most friendly way possible, because some engineers might feel like publishing a code review is actually going to war with the reviewers if the wrong terminology is used. A code review should be a collaboration tool where reviewers help raise the quality of the code the author produced by leaving suggestions or questions in the form of comments. It should never feel like a battle of opinions or tenures, and the tool should assist in this too.

我不是术语专家，但是我可以弄清楚哪种单词选择可能引发或不引起激烈的讨论。 该工具将影响工程师行为的好坏。 我使用了一个工具，将您正在等待作者的更改的短语称为“请求的更改”，旁边带有漂亮的红色X。 这足以使它看起来像是个人的事情，或者似乎必须让代码作者必须接受审阅者的所有“要求更改”的建议，而实际上，您真正想说的是“嘿，我留下了一些评论，并希望在更改合并之前看到他们的回应。” 在映射审阅者状态时，应以最友好的方式调用和表示它们，因为如果使用了错误的术语，一些工程师可能会觉得发布代码审阅实际上会与审阅者发生冲突。 代码审查应该是一种协作工具，审查者可以通过以注释的形式留下建议或问题来帮助提高作者编写的代码的质量。 它永远不应该感觉像是一场观点或任期之战，并且该工具也应该为此提供帮助。

有用的扩展 (Useful extensions)

Often in comments, engineers will express agreement with a peer or link useful external resources from the web or another internal tool. Even something as simple as having upvotes on comments avoids having engineers replying to each other comments with "+1". What would be considered useful will vary a lot among companies, I am pretty sure about that, but there's always the opportunity of ending up creating those which are not useful at all. There's always the tradeoff to remember: any time spent building something could be spent on building something else. One might have spent a lot of time in a crawler for cat memes and the ability to add them as comments to your code reviewing tool or they might spend time integrating your Google Drive instead, it's just a matter of deciding which one makes reviewing code easier.

工程师通常会在评论中表示与同伴的协议，或者从Web或其他内部工具链接有用的外部资源。 即使是简单地评论，也可以避免工程师用“ +1 ”回复彼此的评论。 在公司之间， 有用的东西会有很大的不同，我对此很确定，但是总有机会最终创建根本没有用的东西。 总要记住一个折衷方案：任何花在构建某些东西上的时间都可以花在构建其他东西上。 人们可能在搜寻器上花了很多时间来寻找猫咪模因，并且能够将它们作为注释添加到您的代码审查工具中，或者他们可能会花费时间来集成您的Google云端硬盘，这只是决定哪个使代码审查更容易而已。

搜索支持 (Search support)

Regardless of the client, the code reviews should be searchable and their contents should also be searchable in themselves too. If the engineers do a good job at bookkeeping, then every code change is linked to a task in some system with more context on the change. You should be able to easily find every change that link to that task if you ever need to.

无论客户是谁，代码评论都应该是可搜索的，它们的内容也应该本身可以搜索。 如果工程师在簿记方面做得很好，那么每个代码更改都将链接到某个系统中具有更改上下文的更多任务。 如果需要，您应该能够轻松找到链接到该任务的每个更改。

可扩展性 (Extensibility)

The beauty of extensibility is that it gives you a great power to customise the tool to make it work the way you want to. Data mining, creating bots, automated messages, analysers, rules, you name it. It is very important that the tool is customisable especially for big companies which have different areas working in different ways. Remember the two reviewers policy I mentioned? Well, not every team might want to adopt that, and the tool should be customisable enough to allow for that too.

可扩展性的优点在于，它使您能够自定义工具，使其以所需的方式工作。 您可以命名为数据挖掘，创建漫游器，自动消息，分析器，规则。 该工具是可定制的，这一点非常重要，特别是对于具有不同领域，以不同方式工作的大公司而言。 还记得我提到的两位审稿人政策吗？ 好吧，并不是每个团队都希望采用这种工具，并且该工具应该足够可定制，以允许这样做。

翻译自: https://medium.com/@felipefiali/what-makes-a-good-code-reviewing-tool-good-aa7fe5de2e98

很好的代码笔记