13.4 更高层次的注释增强直觉

注释可以充实代码的第二种方式是提供直觉。这些注释是在比代码更高的层次上写的。它们省略了细节，帮助读者理解代码的整体意图和结构。这种方法通常用于方法内部的注释，以及接口注释。例如，考虑下面的代码：

// If there is a LOADING readRpc using the same session 
// as PKHash pointed to by assignPos, and the last PKHash 
// in that readRPC is smaller than current assigning 
// PKHash, then we put assigning PKHash into that readRPC. 
int readActiveRpcId = RPC_ID_NOT_ASSIGNED; 
for (int i = 0; i < NUM_READ_RPC; i++) {
    if (session == readRpc[i].session 
            && readRpc[i].status == LOADING 
            && readRpc[i].maxPos < assignPos 
            && readRpc[i].numHashes < MAX_PKHASHES_PERRPC) { 
        readActiveRpcId = i; 
        break;
    }
}

这段注释太低层、太详细了。一方面，它部分地重复了代码。“if there is a LOADING readRpc”只是重复了对readRpc[i].status == LOADING的检查。另一方面，注释没有解释这段代码的总体目的，也没有解释它是如何与包含它的方法相适应的。因此，这段注释并不能帮助读者理解代码。

这是一条更好的注释：

// Try to append the current key hash onto an existing 
// RPC to the desired server that hasn't been sent yet.

这条注释不包含任何细节；相反，它在更高层次上描述了代码的整体功能。有了这些高层次的信息，读者可以解释代码中发生的几乎所有事情：循环一定是在所有现有的远程过程调用（RPC）上进行迭代；session检查可能是用来查看某个RPC是否被送到了正确的服务器；LOADING检查表明RPC可以有多种状态，在某些状态下，增加更多的哈希值是不安全的；MAX_PKHASHES_PERRPC检查表明，在一个RPC中可以发送多少哈希值是有限制的。该注释唯一没有解释的是maxPos检查。此外，新的注释为读者提供了一个判断代码的依据：它是否做到了将键的哈希值添加到现有的RPC中所需要的一切？原来的注释并没有描述代码的整体意图，所以读者很难判断代码的行为是否正确。

高层次的注释比低层次的注释更难写，因为你必须以不同的方式来思考代码。问问自己：这段代码想做什么？你能用来解释代码中的一切的最简单的表述是什么？这段代码中最重要的东西是什么？

工程师往往是非常注重细节的。我们喜欢细节，并且善于管理大量的细节；这对于成为一名优秀的工程师是至关重要的。但是，优秀的软件设计师也可以从细节中抽身出来，在更高的层次上思考一个系统。这意味着决定系统的哪些方面是最重要的，并且能够忽略低层次的细节，只从系统最基本的特征来考虑。这就是抽象的本质（找到一种简单的方式来思考一个复杂的实体），这也是你在编写更高层次的注释时必须做的。一个好的高层注释表达了一个或几个提供概念框架的简单想法，例如“附加到一个现有的RPC”。考虑到这个框架，就很容易看出具体的代码语句与整体目标的关系。

这是另一个代码示例，它有一个很好的高层次注释：

if (numProcessedPKHashes < readRpc[i].numHashes) { 
    // Some of the key hashes couldn't be looked up in 
    // this request (either because they aren't stored 
    // on the server, the server crashed, or there 
    // wasn't enough space in the response message). 
    // Mark the unprocessed hashes so they will get 
    // reassigned to new RPCs.
    for (size_t p = removePos; p < insertPos; p++) {
        if (activeRpcId[p] == i) { 
            if (numProcessedPKHashes > 0) { 
                numProcessedPKHashes--; 
            } else { 
                if (p < assignPos) 
                    assignPos = p; 
                activeRpcId[p] = RPC_ID_NOT_ASSIGNED; 
            }
        }
    }
}

这个注释做了两件事。第二句话提供了对代码所做的抽象描述。第一句话是不同的：它（用高层次的术语）解释了为什么（why）要执行代码。“我们如何到达这里”这种形式的注释对于帮助人们理解代码非常有用。例如，当记录一个方法时，描述该方法最可能在什么条件下被调用是非常有帮助的（特别是当该方法只在不寻常的情况下被调用）。