|
审美
大家都愿意读有美感的代码，通过把代码用一致的、有意义的方式“格式化”，可以使代码变得更容易读，并且读的更快。
- 如果多个代码块作相似的事情，尝试让他们有相同的剪影。
- 把代码按“列”对齐可以让代码更容易浏览。
- 如果在一段代码中提到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);
| 
转播
