聊聊代码整洁之道

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注释
不要添加日志式注释，好比修改时间等信息（git能够作的事情）
注释必定是表达代码以外的东西，代码能够包含的内容，注释中必定不要出现
若是有必要注释，请注释意图（why），而不要去注释实现（how)，你们都会看代码
适当添加警示注释

命名

• 尽量使用标准命名方法，好比设计模式，通用学术名词等
• 命名要找更有表现力的词

使用更专业的词，好比不用get而使用fetch或者download
避免空泛的名字，像tmp
使用具体的名字来细致的描述事物
给变量名带上重要的细节，好比加上单位ms等
为做用域大的名字采用更长的名字，做用域小的使用短名字
变量类型为布尔值表达加上is，has，can，should这样的词会更明确

• 变量名称长短应该与其做用域对应
• 别惧怕长名称，长而具备描述性的名称比短而使人费解的名称好
• 函数名称应该说明反作用，名称应该表达函数，变量或类的一切信息，请不要掩盖反作用，好比CreateAndReturnXXX

方法

• 函数不该该有100行那么长，20行封顶最好

if else while等控制语句其中代码块应该只有一行，也就是一个函数调用语句
函数的锁进层次不该该多于两层
一个函数只作一件事，一个函数不该该能抽象出另一个函数

• 某个公共函数调用的私有函数紧随其后
• 最理想的参数是零参数，最长不要超过三个入参，尽可能不要输出参数

若是函数传入三个及以上参数最好将其抽象为类
标识参数十分丑陋，向函数传入布尔值用于区分不一样业务的作法很丑陋，应该拆分为多个函数

• 别返回null值，抛出异常或者返回特殊对象，尽可能避免NPE
• 别传入null值

异常与错误

• 抽离try catch包含的代码块，其中代码块抽象为一个函数
• 抛出的每一个异常，都应当提供足够的环境说明，已便判断错误的来源与处所
• 不要将系统错误归咎于偶然事件

并发

• 分离并发相关代码与其它代码
• 严格限制对可能被共享的数据的访问
• 避免使用一个共享对象的多个同步方法
• 保持同步区域微小，尽量少设计临界区

单元测试

• 不要怕单元测试的方法名字太长或者繁琐，测试函数的名称就像注释
• 不要追求过高的测试覆盖率，测试代码前面90%一般比后面10%花的时间少
• 使用最简单的而且可以完整运用代码的测试输入
• 给测试函数取一个完整性的描述性名字，好比 Test _
• 测试代码与生产代码同样重要
• 若是测试代码不能保证整洁，你就会很快失去他们
• 每一个测试一个断言，单个测试中断言数量应该最小化也就是一个断言
• FIRST原则

快速 Fast

• 独立 Independent 测试应该相互独立

可重复 Repeatable 测试应当在任何环境中重复经过
自足验证 Self-Validating 测试应该有布尔值输出
及时 Timely 最好的方式是TDD

独立 Independent 测试应该相互独立
可重复 Repeatable 测试应当在任何环境中重复经过
自足验证 Self-Validating 测试应该有布尔值输出
及时 Timely 最好的方式是TDD

代码结构

• 代码行长度控制在100-120个字符
• 可能用大多数为200行，最长500行的单个文件构造出色的系统
• 关系密切的代码应该相互靠近

变量声明应该靠近其使用位置
若某个函数调用了另一个，应该把他们放在一块儿，并且调用者应该放在被调用者上面
自上向下展现函数调用依赖顺序

• 应该把解释条件意图的函数抽离出来，尽量将条件表达为确定形式
• 不要继承常量，好比接口中定义常量，不要使用继承欺骗编程语言的做用范围规则
• 模块不该了解它所操做对象的内部状况
• DTO（Data Transfer Objects）是一个只有公共变量没有函数的类
• 对象暴露行为，隐藏数据
• 不要使用“尤达表示法” 如 if(null == obj)，现代编译器对if(obj = null)这样的代码会给出警告
• 通常状况使用if else，简单语句使用三目运算符
• 一般来说提前返回能够减小嵌套并让代码整洁

设计

• 类应该足够短小

类应该知足单一权责原则（SRP），类和模块只有一个修改理由
类应该只有少许的实体变量
类应该遵循依赖倒置原则 DIP（Dependency Inversion Principle），类应该依赖于抽象而不是依赖于具体细节
类中的方法越少越好，函数知道的变量越少越好，类拥有的实体变量越少越好

• 经过减小变量的数量和让他们尽可能“轻量级”来让代码更有可读性

减小变量
缩小变量的做用域
只写一次的变量更好，如常量

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

从项目中消除没必要要的功能，不要过分设计
重新考虑需求，解决版本最简单的问题，只要能完成工做就行
常常性地通读标准库的整个API，保持对他们的熟悉程度

• 简单设计

运行全部测试
不可重复
表达了程序员的意图
尽量减小类和方法的数量
以上规则按重要程度排列

• 不管是设计系统或者单独模块，别忘了使用大概可工做的最简单方案
• 整洁的代码只提供一种而非多种作一件事的途径，他只有尽可能少的依赖。明肯定义并提供尽可能少的API
• 减小重复代码，提升表达力，提前构建，简单抽象

小结

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

本文做者：竹涧

阅读原文

本文为云栖社区原创内容，未经容许不得转载。