注释的目的是确保系统的结构和行为对读者来说是显而易见的，因此他们可以快速找到所需的信息，并有信心对其进行修改，以对系统进行修改。这些信息中的某些信息可以以对读者来说显而易见的方式表示在代码中，但是有大量信息无法从代码中轻易推导出。注释将填写此信息。
当遵循注释应描述代码中不明显的内容的规则时，“明显”是从第一次读取您的代码的人（不是您）的角度出发。在撰写注释时，请尝试使自己进入读者的心态，并问自己他或她需要知道哪些关键事项。如果您的代码正在接受审核，并且审核者告诉您某些不明显的内容，请不要与他们争论。如果读者认为它不明显，那么它就不明显。不用争论，而是尝试了解他们发现的令人困惑的地方，并查看是否可以通过更好的注释或更好的代码来澄清它们。
The goal of comments is to ensure that the structure and behavior of the system is obvious to readers, so they can quickly find the information they need and make modifications to the system with confidence that they will work. Some of this information can be represented in the code in a way that will already be obvious to readers, but there is a significant amount of information that can’t easily be deduced from the code. Comments fill in this information.
When following the rule that comments should describe things that aren’t obvious from the code, “obvious” is from the perspective of someone reading your code for the first time (not you). When writing comments, try to put yourself in the mindset of the reader and ask yourself what are the key things he or she will need to know. If your code is undergoing review and a reviewer tells you that something is not obvious, don’t argue with them; if a reader thinks it’s not obvious, then it’s not obvious. Instead of arguing, try to understand what they found confusing and see if you can clarify that, either with better comments or better code.
回答第 13.5 节中的问题
开发人员是否需要了解以下每条信息才能使用 IndexLookup 类？
- IndexLookup 类发送给包含索引和对象的服务器的消息格式。否：这是应隐藏在类中的实现细节。
- 用于确定特定对象是否在所需范围内的比较功能（使用整数，浮点数或字符串进行比较吗？）。是：该课程的用户需要了解此信息。
- 用于在服务器上存储索引的数据结构。否：此信息应封装在服务器上；甚至 IndexLookup 的实现都不需要知道这一点。
- IndexLookup 是否同时向多个服务器发出多个请求。可能：如果 IndexLookup 使用特殊技术来提高性能，则文档应提供有关此问题的一些高级信息，因为用户可能会在意性能。
- 处理服务器崩溃的机制。否：RAMCloud 可从服务器崩溃中自动恢复，因此崩溃对于应用程序级软件不可见；因此，在 IndexLookup 的接口文档中无需提及崩溃。如果崩溃反映到应用程序中，则接口文档将需要描述它们如何表现出来（而不是崩溃恢复如何工作的详细信息）。
Does a developer need to know each of the following pieces of information in order to use the IndexLookup class?
- The format of messages that the IndexLookup class sends to the servers holding indexes and objects. No: this is an implementation detail that should be hidden within the class.
- The comparison function used to determine whether a particular object falls in the desired range (is comparison done using integers, floating-point numbers, or strings?). Yes: users of the class need to know this information.
- The data structure used to store indexes on servers. No: this information should be encapsulated on the servers; not even the implementation of IndexLookup should need to know this.
- Whether or not IndexLookup issues multiple requests to different servers concurrently. Possibly: if IndexLookup uses special techniques to improve performance, then the documentation should provide some high-level information about this, since users may care about performance.
- The mechanism for handling server crashes. No: RAMCloud recovers automatically from server crashes, so crashes are not visible to application-level software; thus, there is no need to mention crashes in the interface documentation for IndexLookup. If crashes were reflected up to applications, then the interface documentation would need to describe how they manifest themselves (but not the details of how crash recovery works).