编写可读代码的艺术读书笔记--审美与注释

审美

大家都愿意读有美感的代码，通过把代码用一致的、有意义的方式“格式化”，可以使代码变得更容易读，并且读的更快。

如果多个代码块作相似的事情，尝试让他们有相同的剪影。
把代码按“列”对齐可以让代码更容易浏览。
如果在一段代码中提到A、B和C，那么不要在另一段中说B、C和A。
用空行把大块的代码分成逻辑上的“段落”。

该写什么样的注释
为代码中的瑕疵写注释，有几种标记在程序员中很流行：

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

应该记录下来的想法包括：

对于为什么代码写成这样而不是那样的内在理由“指导性批注”。
代码中的缺陷。
常量背后的故事，为什么是这个值，可能选值的范围及其他可选值。
在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的。

注释应当精确地描述函数的行为

假设你刚写了一个函数，它统计一个文件中的行数：

//Returnthe number of lines in this file.

IntCountLines(string filename){…}

上面的注释并不是很精确，因为有很多定义“行”的方式，下面的注释对于这种实现方法更好一些：

//Count how many newlines bytes(‘\n’)are in the file.

Int CountLines(String filename){…}

用输入、输出例子来说明特别的情况

例如，下面是一个用来移除部分字符串的通用函数：

//Remove the suffix/prefix of ‘chars’from the input of ‘src’

String Strip (String src,String chars){…}

这条注释不是很精确，但是一个精心挑选的例子就可以回答这些问题

//Example:Strip(“abba/a/ba”,”ab”)return “/a/”

String Strip(String src, String chars){…}

“具名函数参数”的注释

void Connect(int timeout, booluse_encrption){…}

//Call the function with commentedparameters

Connect(/*timeout_ms= */ 10,/*use_encryption = */ false);