一坨屎案 如何避免自己写的代码成为别人眼中的一坨屎

来自：云栖社区，作者：竹涧

摘要：Any fool can write code that a computer can understand. Good programmers write code that humans can understand. 普通的工程师堆砌代码，优秀的工程师优雅代码，卓越的工程师简化代码。

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

一、注释

不要给不好的名字加注释，一个好的名字比好的注释更重要；

不要“拐杖注释”，好代码 > 坏代码 + 好注释；

在文件/类级别使用全局注释来解释所有部分如何工作；

一定要给常量加注释；

团队统一定义标记：

TODO 待处理的问题；

FIXME 已知有问题的代码；

HACK 不得不采用的粗糙的解决方案；

在注释中用精心挑选的输入输出例子进行说明；

注释应该声明代码的高层次意图，而非明显的细节；

不要在代码中加入代码的著作信息，git可以干的事情不要交给代码；

源代码中的html注释是一种厌物, 增加阅读难度；

注释一定要描述离它最近的代码；

注释一定要与代码对应；

公共api需要添加注释，其它代码谨慎使用注释；

典型的烂注释：

不恰当的信息；

废弃的注释；

冗余注释；

糟糕的注释；

注释掉的代码；

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

不要有循规式注释，比如setter/getter注释；

不要添加日志式注释，比如修改时间等信息；

注释一定是表达代码之外的东西，代码可以包含的内容，注释中一定不要出现；

如果有必要注释，请注释意图，而不要去注释实现是一个只有公共变量没有函数的类；

对象暴露行为，隐藏数据；

不要使用“尤达表示法” 如 if(null == obj)，现代编译器对if(obj = null)这样的代码会给出警告；

一般情况使用if else，简单语句使用三目运算符；

通常来讲提早返回可以减少嵌套并让代码整洁；

八、设计

类应该足够短小：

类应该满足单一权责原则，类和模块只有一个修改理由；

类应该只有少量的实体变量；

类应该遵循依赖倒置原则 DIP，类应该依赖于抽象而不是依赖于具体细节；

类中的方法越少越好，函数知道的变量越少越好，类拥有的实体变量越少越好；

通过减少变量的数量和让他们尽量“轻量级”来让代码更有可读性：

减少变量；

缩小变量的作用域；

只写一次的变量更好，如常量；

最好读的代码就是没有代码：

从项目中消除不必要的功能，不要过度设计；

从新考虑需求，解决版本最简单的问题，只要能完成工作就行；

经常性地通读标准库的整个API，保持对他们的熟悉程度；

简单设计：

运行所有测试；

不可重复；

表达了程序员的意图；

尽可能减少类和方法的数量；

以上规则按重要程度排列；

无论是设计系统或者单独模块，别忘了使用大概可工作的最简单方案；

整洁的代码只提供一种而非多种做一件事的途径，他只有尽量少的依赖。明确定义并提供尽量少的API；

减少重复代码，提高表达力，提早构建，简单抽象；

九、小结

作为代码整洁之道系列的第一篇，本文从注释、命名、方法，单元测试，并发等视角简单给出了一些最佳实践，下文我们会展开来从每个方面介绍更多的实践事例。相信每一个优秀的工程师都有一颗追求卓越代码的心，在代码整洁工程实践上你有哪些好的建议？数百人协作开发的代码如何保证代码整洁一致性？欢迎大家来讨论。