18.1 Things that make code more obvious

Two of the most important techniques for making code obvious have already been discussed in previous chapters. The first is choosing good names (Chapter 14). Precise and meaningful names clarify the behavior of the code and reduce the need for documentation. If a name is vague or ambiguous, then readers will have read through the code in order to deduce the meaning of the named entity; this is time-consuming and error-prone. The second technique is consistency (Chapter 17). If similar things are always done in similar ways, then readers can recognize patterns they have seen before and immediately draw (safe) conclusions without analyzing the code in detail.

在前面的章节中已经讨论了使代码显而易见的两种最重要的技术。首先是选择好名字（第 14 章）。精确而有意义的名称可以阐明代码的行为，并减少对文档的需求。如果名称含糊不清或含糊不清，那么读者将通读代码以推论命名实体的含义；这既费时又容易出错。第二种技术是一致性（第 17 章）。如果总是以相似的方式完成相似的事情，那么读者可以识别出他们以前所见过的模式，并立即得出（安全）结论，而无需详细分析代码。

Here are a few other general-purpose techniques for making code more obvious:

以下是使代码更明显的其他一些通用技术：

Judicious use of white space. The way code is formatted can impact how easy it is to understand. Consider the following parameter documentation, in which whitespace has been squeezed out:

明智地使用空白。代码格式化的方式会影响其理解的容易程度。考虑以下参数文档，其中空格已被压缩：

  1. /**
  2.  *  ...
  3.  *  @param numThreads The number of threads that this manager should
  4.  *  spin up in order to manage ongoing connections. The MessageManager
  5.  *  spins up at least one thread for every open connection, so this
  6.  *  should be at least equal to the number of connections you expect
  7.  *  to be open at once. This should be a multiple of that number if
  8.  *  you expect to send a lot of messages in a short amount of time.
  9.  *  @param handler Used as a callback in order to handle incoming
  10.  *  messages on this MessageManager's open connections. See
  11.  *  {@code MessageHandler} and {@code handleMessage} for details.
  12.  */

It’s hard to see where the documentation for one parameter ends and the next begins. It’s not even obvious how many parameters there are, or what their names are. If a little whitespace is added, the structure suddenly becomes clear and the documentation is easier to scan:

很难看到一个参数的文档在哪里结束而下一个参数的文档在哪里开始。甚至不知道有多少个参数或它们的名称是什么。如果添加了一些空白，结构会突然变得清晰，文档也更容易扫描：

  1. /**
  2.  *  @param numThreads
  3.  *           The number of threads that this manager should spin up in
  4.  *           order to manage ongoing connections. The MessageManager spins
  5.  *           up at least one thread for every open connection, so this
  6.  *           should be at least equal to the number of connections you
  7.  *           expect to be open at once. This should be a multiple of that
  8.  *           number if you expect to send a lot of messages in a short
  9.  *           amount of time.
  10.  *  @param handler
  11.  *           Used as a callback in order to handle incoming messages on
  12.  *           this MessageManager's open connections. See
  13.  *           {@code MessageHandler} and {@code handleMessage} for details.
  14.  */

Blank lines are also useful to separate major blocks of code within a method, such as in the following example:

空行也可用于分隔方法中的主要代码块，例如以下示例：

  1. void* Buffer::allocAux(size_t numBytes) {
  2.     //  Round up the length to a multiple of 8 bytes, to ensure alignment.
  3.     uint32_t numBytes32 =  (downCast<uint32_t>(numBytes) + 7) & ~0x7;
  4.     assert(numBytes32 != 0);
  6.     //  If there is enough memory at firstAvailable, use that. Work down
  7.     //  from the top, because this memory is guaranteed to be aligned
  8.     //  (memory at the bottom may have been used for variable-size chunks).
  9.     if  (availableLength >= numBytes32) {
  10.         availableLength -= numBytes32;
  11.         return firstAvailable + availableLength;
  12.     }
  14.     //  Next, see if there is extra space at the end of the last chunk.
  15.     if  (extraAppendBytes >= numBytes32) {
  16.         extraAppendBytes -= numBytes32;
  17.         return lastChunk->data + lastChunk->length + extraAppendBytes;
  18.     }
  20.     //  Must create a new space allocation; allocate space within it.
  21.     uint32_t allocatedLength;
  22.     firstAvailable = getNewAllocation(numBytes32, &allocatedLength);
  23.     availableLength = allocatedLength numBytes32;
  24.     return firstAvailable + availableLength;
  25. }

This approach works particularly well if the first line after each blank line is a comment describing the next block of code: the blank lines make the comments more visible.

如果每个空白行之后的第一行是描述下一个代码块的注释，则此方法特别有效：空白行使注释更可见。

White space within a statement helps to clarify the structure of the statement. Compare the following two statements, one of which has whitespace and one of which doesn’t:

语句中的空白有助于阐明语句的结构。比较以下两个语句，其中之一具有空格，而其中一个没有空格：

  1. for(int pass=1;pass>=0&&!empty;pass--) {
  3. for (int pass = 1; pass >= 0 && !empty; pass--) {

Comments. Sometimes it isn’t possible to avoid code that is nonobvious. When this happens, it’s important to use comments to compensate by providing the missing information. To do this well, you must put yourself in the position of the reader and figure out what is likely to confuse them, and what information will clear up that confusion. The next section shows a few examples.

注释。有时无法避免非显而易见的代码。发生这种情况时，重要的是使用注释来提供缺少的信息以进行补偿。要做到这一点，您必须使自己处于读者的位置，弄清楚什么可能会使他们感到困惑，以及哪些信息可以消除这种混乱。下一部分显示了一些示例。