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

审美

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

• 如果多个代码块作相似的事情，尝试让他们有相同的剪影。
•   把代码按“列”对齐可以让代码更容易浏览。
• 如果在一段代码中提到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);