《代码整洁之道》整理

Posted 2022-08-01 moongeek

1、命名篇

1. 避免使用误导性的命名，比如是List类型变量才会命名为accountList；不使用小写的字母L和大写的字母O来命名变量，因为他们会和数字1和0混淆
2. 变量的命名使用有区分意义的词。比如，ProductInfo和ProductData就没区分；Info和Data就像the、a、an一样是混淆的废话；变量名不出现Variable，表名不出现Table
3. 类名不出现Manager、Processor、Data、Info这类类名；类名必须是名词
4. 使用工厂来新建对象比new对象要好，可以将构造函数private化，比如Complex.fromRealNameNumber(23.0)比new Complex(23.0)要好
5. 每个概念只使用一个词。比如，fetch、retrive和get表示一个意思，尽量别同时出现多个

2、函数篇

1. 函数应该短小，20行封顶最佳
2. 函数应该只做一件事情，如果一个函数可以继续拆分，则说明该函数不止做了一件事
3. switch 语句如果太长，可以考虑使用 多态 来替代
4. 函数名不要怕长，最好使用描述性的名称，能表达出函数的意义就好
5. 函数参数：
   1. 函数的参数越少越好，最好别超过三个，三个或三个以上可以封装成一个对象
   2. 对于传入单个参数的函数，一种普遍的作用是使用该参数做别的事，另一种是操作该参数本身。这种情况参数名最好能区分这两种形式，比如String transform(StringBuffer in)，告诉读者期望的输入和输出类型。
   3. 如果需要向函数传入布尔值，可能考虑将函数分为两个函数使用
6. 函数名最好由动词加名词组成，比如write(name)就不如writeFiled(name)好，后者清楚知道name是个filed
7. 函数名要明确描述函数所做的所有事情，避免给调用者带来意外的混乱
8. 使用异常代替返回错误码。错误码是在要求调用者立即处理错误，异常可以在后面统一处理
9. 使用了try...catch的代码块最好单独抽离出来一个函数，再调用他，避免把主流程混乱
10. 消除重复的代码

3、注释篇

1. 注释的作用是弥补我们在用代码表达意图时遭遇的失败，所以说，注释是一种失败！

2. 如果遇到需要写注释的情况，可以优先考虑是否能用变量名或方法名来表达，比如下面，第二种表达会更好：

   // 判断员工是否合法，并且年龄大于65岁
   if(employee.flag && employee.age > 65)
   
   if(employee.isEligibleForFullBenefits())

3. 好的注释使用范围：

   1. 表明法律、作者信息
   2. 提供有用的信息，比如对抽象函数注释、对一个正则表达式期望匹配的格式注释等
   3. 阐释，对一个比较难懂的参数或返回值进行说明
   4. 警示，对一些重要代码进行警示，防止别人修改该代码
   5. // TODO对未完成的工作进行注释
   6. 公共API的Javadoc

4. 坏的注释实例：

   1. 多余的注释，比如有无注释意图都很明显的代码

   2. 误导性注释，注释和代码实际行为不符合

   3. 循规式注释，比如要求所有函数都要有Javadoc注释

   4. 能用函数或是变量名时，就别用注释

   5. 括号后后面的注释，本意是好的，但是根本解决方法应该是缩短函数篇幅

      while(xxxx)
        .......
        if(xxx)
            ......
         // if
       // while

   6. 注释掉的不用的代码直接删除，别怕找不回

4、格式篇

1. 封包声明、导入声明和每个函数之间使用 空行 隔开，提高代码的视觉效果

2. 质检关系“亲密”的概念应该相互 靠近，而不是空行隔开
3. 变量的声明应该在 靠近 使用的位置
4. 类成员变量应该声明在类的顶部，循环中变量应该在括号内声明
5. 相关函数，比如A函数调用了B函数，则A和B最好放在一起，而且A放在B上面

6. 每行代码长度最好不要太长，比如最好80个字符，或是100~120个字符内

5、对象和数据结构篇

1. 类的私有变量如果提供了取值器和赋值器，那么它仍然是 暴露 了

2. 墨忒尔定律：模块不该去了解它所操作对象的内部情形。就是说，对象不改通过存取器暴露其内部变量。更准确的说，墨忒尔定律认为，类C的方法f只能调用以下对象的方法：

   1. C
   2. 由f创建的对象
   3. 作为参数传递给f的对象
   4. C的成员变量的对象

   即，方法不该调用任何函数返回的对象的方法，只跟朋友对话，不与陌生人对话

6、其他

1. 函数不要返回控制，避免使用时检查
2. 函数参数不要传递空值
3. 第三方API如果抛出大量异常，可以考虑封装下再使用

说明：本文整理了部分书中观点，有些观点个人感觉有点苛刻不太实用，还有些章节直接略过了。想更详细了解请参考原著。