代码整洁规范之道
有意义的命名
-
见名知意:可轻松根据名称,知道大致用途,而不是使用拼音缩写等,让人费解
-
有意义的区分:用途不同时,名称也记得区分开来,避免因名称类似而导致误用
-
避免使用编码(字母、数字前后缀区分等):不能很好知道用途和差异,增加了理解成本
-
类名、对象名,使用名词或名词短语
-
方法名应是动词或动词短语:方便理解方法要做什么
-
每个概念对应一个词,一以贯之,方便后续查找:
例如表示查找有get/find/obtain/search等,建议使用统一的概念,减少理解和沟通成本
函数
- 简短,避免过长函数,太长可提取为小函数:增强可读性,且小函数可复用,减少主函数修改成本
- 单一职责:一个函数只专注一件事,避免函数臃肿
- 输入参数尽可能少:太多参数增加理解成本,且容易传错参;过多参数可考虑封装为一个实体
- 使用异常替代返回错误码:错误码的判断会导致更深层次的嵌套结构,调用者需要了解错误码,且错误码不好判断是异常还是业务错误
- 提取try/catch代码块为新函数,try/catch只囊括存异常代码:缩小try/catch的粒度,保持性能
- DRY原则,避免重复代码:可将重复代码提取后复用,减少后续代码变更的成本
- 使用第三方库:优先使用类库提供的方法,经过多次验证的代码出现Bug的概率更低,可择优使用;避免自行编写踩坑、重复造轮子
注释
- 注释不能美化糟糕的代码:优雅的代码才是基础,不要试图用过多的注释,来掩盖代码的糟糕
- 用好的代码命名自解释:避免过多冗余的注释
- 警示地方须注释:关键地方添加注释,促使变更时的重视
格式
- 垂直格式
- 向报纸学习
- 不同概念代码块,空行隔开:提升可读性
- 紧密联系的代码,应靠近:高内聚
- 垂直距离
- 局部变量:尽可能靠近其使用位置
- 实体变量:类的顶部声明
- 相关函数:同类中相互调用函数,调用者尽可能放在被调者上面
- 概念相关:相关代码应该放到一起
- 横向格式
- 避免单行过长
- 水平对齐
- 注意缩进层次
编码
- 卫语句返回:对于不符合的条件,使用卫语句快速失败返回,避免过多分支判断
- 避免魔法值:魔法值可能只有当时编写时知道意义,后续理解成本极大;可提取到常量类或者枚举中,统一管理
- 当成员变量值不改变时,优先定义为静态常量
- 注意检验空指针,尤其是链式调用时
- 类成员与方法的可见性最小化:最少知道原则,避免错误调用
- 尽量减少对变量的重复计算
参考文献
《代码整洁之道》
如何写出优雅的代码
25种代码坏味道总结+优化示例