聊聊代码整洁之道

普通的工程师堆砌代码，优秀的工程师优雅代码，卓越的工程师简化代码。如何写出优雅整洁易懂的代码是一门学问，也是软件工程实践里重要的一环。笔者推荐三本经典的书籍《代码整洁之道 》、《编写可读代码的艺术》、《重构:改善既有代码的设计》，下文重点将从注释、命名、方法、异常、单元测试等多个方面总结了一些代码整洁最佳实践，大部分是笔者总结于以上三本书中的精华，也有部分是笔者工程实践的总结。篇幅有限，本文将总结性给出一些实践建议，后续会有文章来给出一些代码整洁之道的事例。

注释

• 不要给不好的名字加注释，一个好的名字比好的注释更重要
• 不要“拐杖注释”，好代码 > 坏代码 + 好注释
• 在文件/类级别使用全局注释来解释所有部分如何工作
• 一定要给常量加注释

• 团队统一定义标记

  • TODO  待处理的问题
  • FIXME  已知有问题的代码
  • HACK 不得不采用的粗糙的解决方案
• 在注释中用精心挑选的输入输出例子进行说明
• 注释应该声明代码的高层次意图，而非明显的细节
• 不要在代码中加入代码的著作信息，git可以干的事情不要交给代码
• 源代码中的html注释是一种厌物, 增加阅读难度
• 注释一定要描述离它最近的代码
• 注释一定要与代码对应
• 公共api需要添加注释，其它代码谨慎使用注释

• 典型的烂注释

  • 不恰当的信息
  • 废弃的注释
  • 冗余注释
  • 糟糕的注释
  • 注释掉的代码

• 唯一真正好的注释是你想办法不去写的注释

  • 不要有循规式注释，比如setter/getter注释
  • 不要添加日志式注释，比如修改时间等信息（git可以做的事情）
  • 注释一定是表达代码之外的东西，代码可以包含的内容，注释中一定不要出现
  • 如果有必要注释，请注释意图（why），而不要去注释实现（how)，大家都会看代码
  • 适当添加警示注释

原文链接