《代码整洁之道》读书笔记

时间 2019-11-10

标签代码整洁之道读书笔记繁體版

原文原文链接

看完《代码整洁之道》以后我受益不浅，但等到本身实践时却很难按照书中给的建议编写出整洁的代码。一方面是规则太多，记不住，另外一方面书上引用了大量示例代码对这些规则进行佐证，在我记不住时亦不方便查阅。因而我把书中的规则摘了出来并加以必定的解释，闲暇时候多过几遍，但愿这些规则时刻警示我，成为个人习惯。php

想看此书却还没开始的人也能够从这篇笔记出发，对笔记中列出的规则有疑问再翻书找答案，相信会比直接啃书来的快一些。java

ps: 未必要严格遵循书中的规则，代码不是八股文。程序员

命名

1.避免误导

"一组帐号"别用accountList表示，List对程序员有特殊含义，能够用accountGroup、bunchOfAccounts、甚至是accounts
不使用区别较小的名称，ZYXControllerForEfficientHandlingOfStrings和ZYXControllerForEfficientStorageOfStrings难以辨别
不使用小写l、大写O做变量名，看起来像常量一、0

2.作有意义的区分

不以数字系列命名(a一、a二、a3)，按照真实含义命名
Product/ProductInfo/ProductData 意思无区别，只统一用一个
别写冗余的名字，变量名别带variable、表名别带table

3.使用可搜索的名称

单字母名称和数字常量很难在上下文中找出。名称长短应与其做用域大小相对应，越是频繁出现的变量名称得越容易搜索(越长)

4.命名时避免使用编码

把类型和做用域编码进名称里增长了解码负担。意味着新人除了了解代码逻辑以外，还须要学习这种编码语言。
别使用匈牙利语标记法(格式：[Prefix]-BaseTag-Name 其中BaseTag是数据类型的缩写，Name是变量名字)，纯属多余
没必要用"m_"前缀来代表成员变量
接口和实现别在名称中编码。接口名IShapeFactory的前导"I"是废话。若是接口和实现必须选一个编码，宁肯选实现，ShapeFactoryImp都比对接口名称编码来的好

5.类名、方法名

类名应当是名词或名词短语，方法名应当是动词或动词短语

6.每一个概念用一个词

fetch、retrieve、get约定一个一直用便可

7.别用双关语

add方法通常语义是：根据两个值得到一个新的值。若是要把单个值加入到某个集合，用insert或append命名更好，这里用add就是双关语了。

8.添加有意义的语境

不多有名称能自我说明，须要用良好命名的类、函数、或者命名空间来放置名称，给读者提供语境，若是作不到的话，给名称添加前缀就是最后一招了。

函数

1.越短小越好

if/else/while语句的代码块应该只有一行，该行应该是一个函数调用语句。
函数的缩进层级不该该多于一层或两层。

2.只作一件事

若是函数只是作了该函数名下同一抽象层上的步骤，则函数只作了一件事。
要判断函数是否不止作了一件事，就是要看是否能再拆出一个函数。

3.每一个函数一个抽象层级

4.switch语句

把switch埋在较低的抽象层级，通常能够放在抽象工厂底下，用于建立多态对象。

5.使用描述性的名称

函数越短小、功能越集中，就越便于取个好名字。
别惧怕长名称，长而具备描述性的名称，要比短而使人费解的名称好，要比描述性的长注释好。
别惧怕花时间取名字。

6.函数参数

参数越少越好，0参数最好，尽可能避免用三个以上参数
参数越多，编写组合参数的测试用例就越困难
别用标识参数，向函数传入bool值是很差的，这意味着函数不止作一件事。能够将此函数拆成两个。
若是函数须要两个、三个或者三个以上参数，就说明其中一些参数应该封装成类了。
将参数的顺序编码进函数名，减轻记忆参数顺序的负担，例如,assertExpectedEqualsActual(expected, actual)

7.反作用(函数在正常工做任务以外对外部环境所施加的影响)

检查密码而且初始化session的方法命名为checkPasswordAndInitializeSession而非checkPassword，即便违反单一职责原则也不要有反作用
避免使用"输出参数"，若是函数必须修改某种状态，就修改所属对象的状态吧

8.设置(写)和查询(读)分离

if(set("username", "unclebob")) { ... } 的含义模糊不清。应该改成:算法

if (attributeExists("username")) { 
    setAttribute("username", "unclebob");
    ...
}

9.使用异常代替返回错误码

返回错误码会要求调用者马上处理错误，从而引发深层次的嵌套结构:编程

if (deletePate(page) == E_OK) {
    if (xxx() == E_OK) {
        if (yyy() == E_OK) {
            log();
        } else {
            log();
        }
    } else {
        log();
    }
} else {
    log();
}

使用异常机制:session

try {
    deletePage();
    xxx();
    yyy();
} catch (Exception e) {
    log(e->getMessage());
}

try/catch代码块丑陋不堪，因此最好把try和catch代码块的主体抽离出来，单独造成函数数据结构
```
try {
    do();
} catch (Exception e) {
    handle();
}
```
函数只作一件事，错误处理就是一件事。若是关键字try在某个函数中存在，它就该是函数的第一个单词，并且catch代码块后面也不应有其余内容。
定义错误码的class须要添加新的错误码时，全部用到错误码class的其余class都得从新编译和部署。但若是使用异常而非错误码，新异常能够从异常class派生出来，无需从新编译或部署。这也是开放闭合原则(对扩展开放，对修改封闭)的范例。

10.不要写重复代码

重复是软件中一切邪恶的根源。当算法改变时须要修改多处地方

11.结构化编程

只要函数保持短小，偶尔出现的return、break、continue语句没有坏处，甚至还比单入单出原则更具备表达力。goto只有在大函数里才有道理，应该尽可能避免使用。

12.如何写出这样的函数

并不须要一开始就按照这些规则写函数，没人作获得。想些什么就写什么，而后再打磨这些代码，按照这些规则组装函数。

注释

若编程语言足够有表现力，咱们就不须要注释。
注释老是一种失败。
代码在演化，注释却不老是随之变更。
不许确的注释比没注释坏的多。

1.用代码来阐述

建立一个与注释所言同一事物的函数便可并发

// check to see if the employee is eligible for full benefits
if ((employee.falgs & HOURLY_FLAG) && (employee.age > 65))

应替换为app

if (employee.isEligibleForFullBenefits())

2.好注释

法律信息
提供基本信息，如解释某个抽象方法的返回值
对意图的解释，反应了做者某个决定后面的意图
阐释。把某些晦涩的参数或者返回值的意义翻译成可读的形式(更好的方法是让它们自身变得足够清晰，可是相似标准库的代码咱们没法修改):less
```
if (b.compareTo(a) == 1) //b > a
```
警示。// don't run unless you have some time to kill
TODO注释
放大一些看似不合理之物的重要性

3.坏注释

自言自语
多余的注释。把逻辑在注释里写一遍不能比代码提供更多信息，读它不比读代码简单。一目了然的成员变量别加注释，显得不少余。
误导性注释
遵循规矩的注释。每一个函数都加注释、每一个变量都加注释是愚蠢的。
日志式注释。有了代码版本控制工具，没必要在文件开头维护修改时间、修改人这类日志式的注释

能用函数或者变量表示就别用注释:

// does the module from the global list <mod> 
// depend on the subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())

能够改成

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

位置标记。标记多了会被咱们忽略掉:
///////////////////// Actions //////////////////////////

右括号注释

try {
    while () {
        if () {
            ...
        } // if
        ...
    } // while
    ...
} // try

若是你想标记右括号，其实应该作的是缩短函数

署名 /* add by rick */ 源代码控制工具会记住你，署名注释跟不上代码的演变。
注释掉的代码。会致使看到这段代码其余人不敢删除
信息过多。别在注释中添加有趣的历史话题或者无关的细节
没解释清楚的注释。注释的做用是解释未能自行解释的代码，若是注释自己还须要解释就太遗憾了。
短函数的函数头注释。为短函数选个好名字比函数头注释要好。
非公共API函数的javadoc/phpdoc注释。

代码格式

1.垂直格式

短文件比长文件更易于理解。平均200行，最多不超过500行的单个文件能够构造出色的系统
区隔: 封包声明、导入声明、每一个函数之间，都用空白行分隔开，空白行下面标识着新的独立概念
靠近: 紧密相关的代码应该互相靠近，例如一个类里的属性之间别用空白行隔开
变量声明应尽量靠近其使用位置：循环中的控制变量应该老是在循环语句中声明。
成员变量应该放在类的顶部声明，不要四处放置
若是某个函数调用了另一个，就应该把它们放在一块儿。咱们但愿底层细节最后展示出来，不用沉溺于细节，因此调用者尽量放在被调用者之上。
执行同一基础任务的几个函数应该放在一块儿。

2.水平格式

一行代码没必要死守80字符的上限，偶尔到达100字符不超过120字符便可。
区隔与靠近: 空格强调左右两边的分割。赋值运算符两边加空格，函数名与左圆括号之间不加空格，乘法运算符在与加减法运算符组合时不用加空格(a*b - c)
没必要水平对齐。例如声明一堆成员变量时，各行不用每个单词都对齐。
短小的if、while、函数里最好也不要违反缩进规则，不要这样:
if (xx == yy) z = 1;

对象和数据结构

对象:暴露行为(接口),隐藏数据(私有变量)
数据结构:没有明显的行为(接口),暴露数据。如DTO(Data Transfer Objects)、Entity

1.对象与数据结构的反对称性(参考书中代码清单6-5)

使用数据结构便于在不改动如今数据结构的前提下添加新函数；使用对象便于在不改动既有函数的前提下添加新类。
使用数据结构难以添加新数据结构，由于必须修改全部函数；使用对象难以添加新函数，由于必须修改全部类。
万物皆对象只是个传说，有时候咱们也会在简单数据结构上作一些过程式的操做。

2.Demeter定律(最少知识原则)

模块不该该了解它所操做对象的内部情形
class C的方法f只应该调用如下对象的方法:
- C
- 在方法f里建立的对象
- 做为参数传递给方法f的对象
- C持有的对象
方法不该调用 由任何函数返回的对象 的方法。下面的代码违反了demeter定律:
final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();
一个简单例子是，人能够命令一条狗行走（walk），可是不该该直接指挥狗的腿行走，应该由狗去指挥控制它的腿如何行走。

异常处理

异常处理很重要，但若是异常处理四处分散在代码中致使逻辑模糊不清，它就是错的。

1.使用异常而不是返回错误码

若是使用错误码，调用者必须在函数返回时马上处理错误，但这很容易被咱们忘记。
错误码一般会致使嵌套if else

2.先写try-catch语句

当编写可能会抛异常的代码时，先写好try-catch再往里堆逻辑

3.使用unchecked exception(java独有)

4.在catch里尽量的记录错误信息，记录失败的操做以及失败的类型。

5.根据调用者的须要定义不一样的异常处理类

同一个try里catch多个不一样exception，可是catch处理的事(打日志等)是一致的，能够考虑用函数打包一下这个异常处理，针对不一样异常仅需throw成同一个异常而不作任何处理，在外层catch时统一处理(打日志等)。若是仅想捕获一部分异常而放过其余异常，就使用不一样的函数打包这个异常处理。

6.特例模式: 建立一个类来处理特例。

try {
    MealExpendses expenses = expenseRepotDAO.getMeals(employee.getID());
    m_total += expenses.getTotal();// 若是消耗了餐食，计入总额
} catch (MealExpensesNotFound e) {
    m_total += getMealPeDiem();// 若是没消耗，将员工补贴计入总额
}

异常打断了业务逻辑。能够在getMeals()里不抛异常，而是在没消耗餐食的时候返回一个特殊的MealExpense对象(PerdiemMealExpense)，复写getTotal()方法。

MealExpendses expenses = expenseRepotDAO.getMeals(employee.getID());
m_total += expenses.getTotal();

publc class PerDiemMealExpenses implements MealExpenses {
    public int getTotal() {
        //return xxx; //返回员工补贴
    }
}

7.别返回null值

返回null值只要一处没检查null，应用程序就会失败
当想返回null值的时候，能够试试抛出异常，或者返回特例模式的对象。

8.别传递null值

在方法中传递null值是一种糟糕的作法，应该尽可能避免。
在方法里用if或assert过滤null值参数，可是仍是会出现运行时错误，没有良好的办法对付调动者意外传入的null值，恰当的作法就是禁止传入null值。

边界

将第三方代码干净利落地整合进本身的代码中

1.避免公共API返回边界接口，或者将边界接口做为参数传递给API。将边界保留在近亲类中。

2.不要在生产代码中试验新东西，而是编写测试来理解第三方代码。

3.避免咱们的代码过多地了解第三方代码中的特定信息。

单元测试

1.TDD(Test-driven development)三定律

First Law: You may not write production code until you have written a failing unit test.
Second Law: You may not write more of a unit test than is sufficient to fail, and not compiling is failing.
Third Law: You may not write more production code than is sufficient to pass the currently failing test.

2.保持测试整洁

脏测试等同于没测试，测试代码越脏生产代码越难修改。
测试代码和生产代码同样重要。
整洁的测试代码最应具备的要素是：整洁性。测试代码中不要有大量重复代码的调用。

3.每一个测试一个断言

每一个测试函数有且仅有一个断言语句。
每一个测试函数中只测试一个概念。

4.整洁的测试依赖于FIRST规则

fast: 测试代码应该可以快速运行，由于咱们须要频繁运行它。
independent: 测试应该相互独立，某个测试不该该依赖上一个测试的结果，测试能够以任何顺序进行。
repeatable: 测试应能够在任何环境中经过
self-validating: 测试应该有bool值输出，不该经过查看日志来确认测试结果，不该手工对比两个文本文件确认测试结果。
timely: 及时编写测试代码。单元测试应该在生产代码以前编写，不然生产代码会变得难以测试。

类

1.类的结构组织(顺序):

公共静态常量
私有静态变量
私有实体变量
公共函数
私有工具函数

2.类应该短小

对于函数咱们计算代码行数衡量大小，对于类咱们使用权责来衡量。
类的名称应当描述其权责。类的命名是判断类长度的第一个手段，若是没法为某个类命以准确的名称，这个类就太长了。类名包含模糊的词汇，如Processor、Manager、Super，这种现象就说明有不恰当的*权责汇集状况。
单一权责原则: 类或者模块应该有一个权责——只有一条修改的理由(A class should have only one reason to change.)。
系统应该由许多短小的类而不是少许巨大的类组成。
类应该只有少许的实体变量，若是一个类中每一个实体变量都被每一个方法所使用，则说明该类具备最大的内聚性。建立最大化的内聚类不太现实，可是应该以高内聚为目标，内聚性越高说明类中的方法和变量互相依赖、互相结合造成一个逻辑总体。
保持内聚性就会获得许多短小的类。若是你想把一个大函数的某一小部分拆解成单独的函数，拆解出的函数使用了大函数中的4个变量，没必要将4个变量做为参数传递到新函数里，仅需将这4个变量提高为大函数所在类的实体变量，可是这么作却由于实体变量的增多而丧失了类的内聚性，更好多作法是让这4个变量拆出来，拥有本身的类。将大函数拆解成小函数每每是将类拆分为小类的时机。

3.为修改而组织(参考书中代码清单10-九、10-10)

类应当对扩展开放，对修改封闭(开放闭合原则)
在理想系统中，咱们经过扩展系统而非修改现有代码来添加新特性。

系统

1.将系统的构造与使用分开

将所有构造过程搬迁到main或者被称之为main的模块中，涉及系统其他部分时，假设全部对象都已经正确构造。
有时应用程序也须要负责肯定什么时候建立对象，咱们可使用抽象工厂模式让应用自行控制什么时候建立对象，但构造能力在工厂实现类里，与使用部分分开。
依赖注入(DI)，控制反转(IoC)是分离构造与使用的强大机制。

emergent design

四条规矩帮助你建立优良的设计

1.运行全部测试

紧耦合的代码难以编写测试，测试写的越多，就越会遵循依赖注入之类的规则，使代码加减小耦合。
测试消除了对清理代码就会破坏代码的恐惧。

2.消除重复

两个方法提取共性到新方法中，新方法分解到另外的类里，从而提高其可见性。

模板方法模式是消除重复的通用技巧

// 原始逻辑
public class VacationPolicy() {
    public void accrueUSDivisionVacation() {
        //do x;
        //do US y;
        //do z;
    }
    public void accrueEUDivisionVacation() {
        //do x;
        //do EU y;
        //do z;
    }
}

// 模板方法模式重构以后
abstract public class VacationPolicy {
    public void accrueVacation() {
        x();
        y();
        z();
    }
    private void x() {
        //do x;
    }
    abstract protected void y() {
    
    }
    private void z() {
        //do z;
    }
}
public class USVacationPolicy extends VacationPolicy {
    protected void y() {
        //do US y;
    }
}
public class EUVacationPolicy extends VacationPolicy {
    protected void y() {
        //do EU y;
    }
}

3.表达意图

做者把代码写的越清晰，其余人理解代码就越快。
太多时候咱们深刻于要解决的问题中，写出能工做的代码以后，就转移到下一个问题上，没有下足功夫调整代码让后来者易于阅读。多少尊重一下咱们的手艺，花一点点时间在每一个函数和类上。

4.尽量少的类和方法

为了保持类和函数的短小，咱们可能会早出太多细小的类和方法。
类和方法数量太多，有时是由毫无心义的教条主义致使的。

5.以上4条规则优先级依次递减。重要的是测试、消除重复、表达意图。

并发编程

1.防护并发代码问题的原则与技巧

遵循单一职责原则。分离并发代码与非并发代码
限制临界区数量、限制对共享数据的访问。
避免使用共享数据，使用对象的副本。
线程尽量地独立，不与其余线程共享数据。