《代码整洁之道》笔记

有意义的命名

1. 名副其实

命名要明确说明其作用，让人一看到就知道是干啥的，不能用比较模糊的词汇。
发现更好的名字应及时替换。

// 反例
int d; // 消逝的时间，以日计

// 正例
int elapsedTimeInDays;

2. 避免误导

不要用其他系统、语言的关键字命名。
避免两个变量使用很长又很相似的命名。
不要使名称与本意相悖。
不要用 l、O 等容易看错的字母命名。

3. 做有意义的区分

名称应提供正确的信息，让人能知道其中的含义和不同之处。
去掉无意义的词汇。

// 反例

int a1;
int a2;
int a3;

getActiveAccount();
getActiveAccounts();
getActiveAccountInfo();

4. 使用读得出来的名称

命名应该能够读得出来，不然不便于记忆和讨论。

// 反例
Date genymdhms;

// 正例
Date generationTimestamp;

5. 使用可搜索的名称

名称的长短应与其作用域大小相对应，单字母名称仅用于短方法中的本地变量。
太多重复的名称导致搜索时困难，修改时容易疏漏。

// 反例
int sum = todayNum + 7;

// 正例
public static final int SYSTEM_NUM = 7;
int sum = todayNum + SYSTEM_NUM;

6. 避免使用编码

不要把类型或作用域写进名称里。

// 反例
PhoneNumber phoneString; // 类型变了，名称没变

不要加前缀

// 反例

String m_dsc;

interface IShapeFactory {} // 接口别加 I 前缀

7. 避免思维映射

不要让读者把你的名称翻译成他们熟知的名称。

8. 类名

类名和对象名应该是名词或名词短语。

9. 方法名

方法名应该是动词或动词短语。

10. 别扮可爱

名字不要耍宝，不要用俗语、俚语或与文化政治相关的词汇。

11. 每个概念对应一个词

fetch、get、find 等相同含义的词应该选择一个。

// 反例
User findUserByName();
User getUserById();

12. 别用双关语

避免将同一个词用于不同的目的或概念。

13. 使用解决方案领域名称

用计算机科学术语、算法名、模式名、数学术语命名。
只有程序员才会读你的代码，要取个技术性的名称。

14. 使用源自所涉问题领域的名称

若不能用程序员熟悉的术语命名，就应采用所涉问题领域的名称。至少，负责维护的人就能去请教该领域的专家。

15. 添加有意义的语境

通过良好的类、函数、命名空间来放置名称，给读者提供语境。
具体体现在：将多个相关的变量提到一个类中，这样通过查看一个 name 变量的类，就知道是什么东西的 name 了。

16. 不要添加没用的语境

不要使多个类名都用同一个前缀，这样 IDE 搜索也麻烦。（如：将一个“加油站豪华版 Gas Station Deluxe”的应用，每个类都添加 GSD 前缀）
语境名称要短要清楚，删掉不必要的词汇。

函数

1. 短小

建议 20 行封顶。
函数作用要一目了然。
每个函数会依序把你带到一下个函数。
函数的缩进层级不应超过两层。（减少 if 等嵌套）

2. 只做一件事

函数应只做一件事，做好这件事。
判断依据：函数是否只是做了该函数名下同一抽象层上的步骤。

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

让代码拥有自顶向下的阅读顺序，即抽离出的函数紧跟在源函数下面。

4. 使用描述性的名称

描述函数做的事。
命名方式要保持一致。
使用与模块名一脉相承的词给函数命名。

5. 函数参数

零参数：最理想
一参数：其次
二参数：再次
三个及以上参数：尽量避免，可以封装为类。

避免使用输出类型的参数，应将其作为返回类型，通过返回值返回。

不要将布尔值作为参数，应该拆成两个函数。

6. 分隔指令与询问

函数要么做什么事，要么回答什么事，二者不可兼得。

// 反例
if (set("username", "unclebob"))...

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

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

抽离 try/catch 代码块的主体部分，形成另外的函数，这个函数也只应该做错误处理这一件事。

8. 别重复自己

消除重复代码。

注释

1. 注释不能美化糟糕的代码

带有少量注释的整洁而有表达力的代码远强于带有大量注释的零碎而复杂的代码。
尽量减少注释，花时间整理好代码。

2. 用代码来阐述

将本来打算写成注释的内容，尽可能简单而明确的用代码写出来。

3. 坏注释

• 循规式，如函数的入参注释
• 署名、日期
• 注释掉的代码
• 函数头

格式

良好的格式易于维护、扩展和沟通。

1. 垂直格式

• 单文件 200 行，最多 500 行
• 函数间用空白行隔开
• 相关代码应该靠近，不要有空行，相关函数要临近

2. 横向格式

• 一行尽量不超过 80 字符
• 用空格隔开相关性较弱的事物
• 变量的水平对齐没什么用
• 注意缩进，用 4 个空格代替 tab

对象和数据结构

• 不暴露数据和实现，采用抽象
• 数据传送对象 dto vo 的使用

错误处理

• 使用异常而非返回码
• 定义常规流程，不要用异常控制流程逻辑
• 别返回 null
• 非必要时，别传递 null

类

• 短小，通过权责判断，类要保持单一权责
• 高内聚：变量和方法相互依赖

---

全文完
2019年2月20日10:32:57