> For the complete documentation index, see [llms.txt](https://zijinshi.gitbook.io/google/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zijinshi.gitbook.io/google/index/comments.md).
# 怎样写代码审核的评论？
## 概述
* 保持友善。
* 解释原因。
* 给出明确的信息，指出问题所在，让开发者最后做决定。
* 鼓励开发者简化代码，给代码添加注释，而不是向你解释为什么这么复杂。
## 礼貌
在审核代码时，礼貌和尊重都很重要，与此同时，评论应该描述清晰，有利于开发者改进代码。确保你对代码的评论应该是针对“代码”，而不是针对“开发者”本人。当然，不必总是遵循这条原则，但是当你要说某些可能让人沮丧或引起争议的话时，一定要对事不对人。例如：
不好的说法：“为什么**你**在这儿使用线程？明显这儿使用并发没有任何好处。”
好的说法：“这儿的并发模型增加了系统的复杂度，我在性能上没有看到好处。因为没有性能提升，这段代码最好还是由多线程改成单线程。”
## 解释为什么
从上面“好的说法”中，我们看到，它有助于开发者理解 *为什么* 你要写这条评论。当然，不必每次都解释为什么，但某些情形——阐明你的意图、你正在遵循的最佳实践、你在提升代码健康程度——解释原因是有必要的。
## 提供指导
**一般而言，修复 CL 的责任人是开发者，而不是审核者。** 你不必为开发者写出详细的设计方案，也不必为他写代码。
但这不代表审核者可以不提供任何帮助。作为审核者，你应该在指出问题所在与提供直接指导之间做好平衡。指出问题，并让开发者自己做决定，这样有助于开发者自我学习，审核者自己也很省时间。这种方式，开发者也更容易找出更好的解决方案，因为相对审核者，开发者对自己的代码更熟悉。
当然，有些时候也可以给出直接的指示、建议或代码。毕竟，代码审核的首要目标是尽可能让 CL 变得更好；次要目标才是提升开发者的技能，以缩短审核时间。
谨记，人不仅能从那些可以做得更好的事情学到知识（译者注：可以做得更好，意味着还有提升的空间），还可以通过强化那些已经做得好的事情学到知识。如果你发现某个 CL 你很喜欢，也请加上评论。例如，，开发人员清理了混乱的算法，添加了教科书级的测试用例覆盖率，或者作为审核人，你从 CL 中学到了知识。就像所有的评论一样，在评论中加上你喜欢某些内容的原因，进一步鼓励开发人员继续良好的实践。
## 标记评论的严重程度
标记评论的严重程度，旨在把必需的修改与指南、建议区分开来。
如下是一些建议：
> Nit： 这是件小事。技术上讲你应该这么做，但不这么做影响也不大。\
> 可选（或考虑）：我认为这是个好主意，但不是必须这么做。\
> FYI： 我并不期望你在这个 CL 中这样做，但你会发现如果考虑长远一点，它会很有趣。
这使得评论意图明确，并帮助作者优先考虑各种评论的重要性。它还有助于避免误解，例如，如果没有评论标签，开发人员可能会误以为这些修改是强制的，即使某些评论只是为了提供信息，或者告知它只是可选方案。
## 接受解释
如果某段代码你看不懂，让开发者解释，通常结果是他们会**重写代码让它更清晰**。有时候，添加注释也可以，只要它不是用来解释一段过于复杂的代码。
**仅仅把解释写到代码审核工具里不利于以后的代码阅读者。** 只有几种情况可以这样，如当你正在审核一段你并不是很熟悉的代码时，开发者向你解释的文字，其他开发者都知道，那这种解释就不必写到代码里。
下一章：[代码评论被拒绝时，应如何处理？](/google/index/pushback.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://zijinshi.gitbook.io/google/index/comments.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.