Bookcold's Blog

“别给糟糕的代码加注释——重新写吧”

                                                   Brian W.Kernighan与P.J.Plaugher

1. 注释不能美化糟糕的代码 2. 用代码来阐述 3. 好注释 法律信息 提供信息的注释 如：解释正则表达式的作用 对意图的解释 阐释 对于某些不能修改的代码，阐释其含义 警示 TODO注释 TODO是程序员认为应该做，但由于某些原因目前还没做的工作 放大 放大某种看来不合理之物的重要性 4. 坏注释 喃喃自语 仅只是因为觉得应该或者因为过程需要就添加注释 多余的注释 误导性的注释 注释往往不够精确 循规式注释 日志式注释 废话式注释 能用函数或变量时就别用注释 位置标记 不要滥用标记栏 括号后面的注释 如：标记循环结束的括号 //while 归属或署名 源代码控制系统是这类信息最好的归属地 注释掉的代码 HTML注释 非本地信息 信息过多 不明显的联系 注释及其描述的代码之间的联系应该显而易见 [...]

1. 短小

每个函数都一目了然。每个函数都只做一件事。并且每个函数都依序把你带到下一个函数。这就是函数应该达到的短小程度。函数的代码块缩进层级不该多于一层或两层。这样的函数易于阅读和理解。

2. 只做一件事

函数应该做一件事。做好这件事。只做一件事。函数只是做了该函数名下同一抽象层上的步骤，则函数还是只做了一件事。

3. 每个函数一个抽象层级

自顶向下读代码——向下规则：要让每个函数后面都跟着位于下一抽象层级的函数，这样，在查看函数列表时，就能按照抽象层级向下阅读了。

4. 使用描述性名称

长而具有描述性的名称要比短而令人费解的名称好。长而具有描述性的名称，要比描述性的注释好。

5. 函数参数

最理想的参数数量是零。参数与函数名处在不同的抽象层级，它要求你了解目前并不特别重要的细节。从测试角度看，参数越多越难测试。

6. 无副作用

函数承诺只做一件事，但还是会做其他被藏起来的事，这些事都是具有破坏性的，可能导致古怪的时序性耦合及顺序依赖。

7. 分割指令与询问

函数要么做什么事，要么回答什么事，但二者不可兼得。

8. 使用异常替代返回错误码

使用异常处理替代返回错误码，错误处理代码能从主路径代码中分离出来。

抽离try/catch代码块，它们把错误处理与正常流程混为一谈。下面的写法更优雅： public void delete(){ try{ deletePage(); } catch (Exception e){ logError(e); } } private void logError(Exception e) { } private void deletePage() { }

错误处理就是一件事 9. 别重复自己 10. [...]

1. 名副其实 选个好名字要花时间，但省下来的时间比花掉的多 一旦发现有更好的名称，就换掉旧的 2. 避免误导 避免留下隐藏代码本意的错误线索 避免使用与本意相悖的词 如：不用accountList来指代一组账号，出非它真的是List类型 3. 做有意义的区分 命名并不仅仅只是为满足编译器的需要 如：一个ProductInfo类和ProductData类，它们名称虽然不同，意思却无区别。 4. 使用读得出来的名称 不要随意自造词 5. 使用可搜索的名称 长名称胜于短名称，搜得到的名称胜于用自造编码代写的名称 单字母名称仅用于短方法中的本地变量 名称长短与其作用域大小相对应 6. 避免使用编码 匈牙利标记法（HN） 在现代编译器的情况下，已经过时了 成员前缀 应当把类和函数做得足够小，消除对成员前缀的需要 接口和实现 接口的前导字母I被滥用。通常并不想让用户知道提供使用的是接口 7. 避免思维映射 不应当让读者在脑中把你的名称翻译为他们熟知的名称 这种问题经常出现在选择是使用问题域术语还是解决方案领域术语时 8. 类名 类名和对象名应该是名词或名词短语 类名不应当时动词 9. 方法名 方法名应当是动词或动词短语。属性访问器、修改器和断言应该根据其值命名，并可加上get、set和is前缀。 10. 别扮可爱 切忌华而不实！言到意到！ 11. 每个概念对应一个词 给每个抽象概念选一个词，并且一以贯之 12. 别用双关语 避免将同一词用于不同目的 同一术语用于不同概念，就算是双关语了 13. 使用解决方案领域名称 使用计算机科学术语，尽量不使用用所涉领域名称来命名。因为只有程序员会读你的代码。 14. [...]