《编写可读代码的艺术》读书笔记——注释

  注释是代码中很重要的提示，当你在阅读别人的或者自己以前写过的代码时往往能够起到一个“指点迷津”的作用。这篇读书笔记将内容划分为三个部分：

Part 1：哪些情况不需要注释
Part 2：哪些情况需要注释
Part 3：怎么写出言简意赅的好注释

<h3>Part 1：哪些情况不需要注释</h3>

• 不要为那些从代码本身就能快速推断的事实写注释
  Q：为什么说有的时候没有注释比有注释更好？
  A：这个问题可以用文中的一段开场白来回答。

阅读注释会占用阅读真实代码的时间，并且每条注释都会占用屏幕上的空间。那么，它最好是物有所值的。

下面抛出一段“坏味道”的注释，感受一下：

//The class definition for Account
public Account{
  //Construtor
  Account();

  //set the profit member to a new value
  void setProfit(double profit);

  //return the profit from this Account
  double getProfit();
}

从这段“坏掉”的注释中可以看出来，它所附带的信息对于是毫无价值的，况且代码量又不能用来衡量KPI，所以绝对杜绝写这种注释。

• 不要为不好名字写注释
  想要写出“可读”的代码，那么为常量、变量、函数起一个好的名字就是第一步（怎么写？以后我将补上，本文只讨论注释）。但是很多时候我们“懒得”去想一个好的名称而不得不补上一堆解释作用的注释。一个好的名字不一个好的注释更重要，注释只会出现多次，而函数或变量却会出现多次。

---

<h3>Part 2：哪些情况需要注释</h3>
  很多好的注释仅通过“记录你的想法”就能得到，也就是那些你在写代码时的重要想法。从写代码的角度来看，以下几种情况需要注释。

• ** 加入“导演评论”**

Q：什么是“导演评论”？

“导演评论”就是电影制作者在电影中给出自己的见解并通过讲故事来帮助你理解这部电影是如何制作的。同样，你应该在代码中也加入注释来记录你对代码有价值的见解。

下面给出文中的例子：

//出乎意料的是，对于这些数据用二叉树比用哈希表快40%
//哈希运算的代价比左/右比较大得多

另一个例子：

//作为整体可能会丢掉几个词。这没有问题。要100%解决太难了

当然，注释也可以用来解释为什么代码写得不那么整洁（这可不是说鼓励代码写得很随意），或者是提醒继任者是时候戴上重构的帽子了：

//这个类正在变得越来越乱
//也许我们应该建立一个‘ResourceNode’子类来帮助整理

• 代码中存在瑕疵
  当代码存在以下问题是，可以采用表中相应的注释：

标记	意义
TODO	还没处理的事
FIXME	已知的无法运行的代码
HACK	对一个问题不得不采用的比较粗糙的解决方案
XXX	危险！这里有重要的问题

给出一个例子：

// TODO 采用更快的算法

• 常量加注释
  当定义常量时，通常在常量的背后都有一个关于它是什么或为什么它是这个值的故事。作为程序员，选择这个某个值的原因往往是读代码的人不知道的，为了避免读者可以去猜测，最好为常量值写上注释。

NUM_THREADS = 8; //设置为1太小了，设置成50又太夸张了

站在读者的角度，以下几种情况也是需要注释的：

• 意料之中的提问
  对于某些代码，当你意识到别人在读的时候可能产生“为什么这样”的疑问时，就要为这部分代码加上注释了。

//Force vector to relinquish its merory
vector<float>().swap(data);

• 公布可能的陷阱
  当你意识到代码可能有什么出人意料的情况，也要附上注释。

//运行时间将达到0，所以小心严重嵌套的输入
def FixBrokenHtml(html): …

• “全局观”注释
  当团队有新成员加入时，具备“全局观”的注释将很快的让能读懂原来的代码。给出一个例子：

//这个文件包含了一些辅助函数，为我们的文件系统提供了更便利的接口
//它处理了文件权限以其他基本的细节

• “总结性”注释
  “总结性”注释和“全局观”注释有点相似，但它往往是一个类或函数内部的，为多个函数或程序语句做一个总结。给出一个例子：

//数据库连接参数
private String classname="com.mysql.jdbc.Driver";
private String dbConntctedURL = "*******";
private String user = "root";
private String password = "*******";

---

Part 3：怎么写出言简意赅的好注释###

• 克服“作者心理阻滞”
  Q：什么是“作者心理阻滞”？
  A：简单来说，就是程序员“懒得”去写的那种“懒”（言简意赅哈哈哈）。
  想要克服“作者心理阻滞”，唯一的办法就是写。刚开始可以先写下心中想的，然后逐渐的提炼，改进。多次循环过后你就达到信手拈来的境界了。下面是书中提到具体操作的几个要点：
• 声明代码的意图
• 让注释保持紧凑
• 采用信息量高的词
• 润色粗糙的句子
• 避免使用不明确的代词
  例子：

//Insert the data into the cache, but check if it's too big fist

“it”所指究竟是data还是cache?如果改为下面的就好理解多了

//Insert the data into the cache, but check if the data too big fist

• 精确的描述函数的行为
  假设你写了一个函数，它统计一个文件中的行数：

//Return the number of lines in this file.
int CountLines(String filename);

上面的注释并不是很精确，因为它存在歧义，或者说还有几种特别的情况：

• “”（空文件）——0或1行？
• “hello”——0或1行？
• “hello\n”——1或2行？
• “hello\n world”——1或2行？

   但如果你写的注释是这样的：

//Count how many newline bytes('\n') are in the file
int CountLines(String filename);

• 用输入/输出例子来说明特别的情况
  对于注释，有时候一个精心挑选的输入/输出例子比千言万语还有效。

//Remove the suffix/prefix of 'chars' from the input 'src'
String Strip(String src, String chars)();

看了上面的注释，问题来了：chars是整个要移除的子串，还是一组无序的字母？如果在src结尾有多个chars会怎么样？显然，精心挑选的例子就可以完美的回答问题：

//…
//Example：Strip("ab", "a") returns "/a/"
String Strip(String src, String chars)();