代码整洁之道

人最大的痛苦，就是无法跨越知道和做到的鸿沟 ------罗翔

该篇不写那些费脑的硬知识点了，聊点认知方面，些许轻松点的话题： 代码整洁之道。

对本职工作认真负责，是一种基本素养，对于一线正在撸代码的程序员，写好代码是一种天职，所以给我个人给本篇再加一个副标题------ 程序员职业素养。

引子

编程文化拥有悠久的历史，这个话题也被前辈们广泛讨论过，本人也在不同场合中和朋友、同事零零碎碎的聊过一些，还在某乎上回答过几个问题，之所以再正式的聊这个话题，是因为在近期我司产品研发部总监做了一次分享，叫做代码整洁之道，听完还是有所触动。

声明：该篇不是照本宣科，是《代码整洁之道》+ 总监的技术分享 + 自身工作经历结合。

在座有多少人读过此书？我认为这本书应该是所有程序员都需要去读的。
有谁曾为自己写了一段好的代码沾沾自喜？
又有谁在过了许久看自己之前写的代码有过感触：写的依旧不错/糟糕透顶？

这是来自分享开篇的一些发问，不知是否触动了各位读者，大家也可以在心中回答一下，沉思过后相信各位读者会有些话要说，对于已经手撸千万行的你，也一定有自己的一套"代码整洁之道"，我们不妨一起走过下文，在这过程中对比一下你心中的"道"。

本文目的：重温一些代码整洁之道，希望可以给日常撸业务的你带来一些动力/兴致/小幸福。

为什么要写整洁的代码

说这个问题，我们反向的想一下，面对不整洁的代码会怎么样（"屎山"），是不是有很多话想说，我来起个头，说一下本人曾吐槽过的（代码就不上图了）：

这么复杂的逻辑，变量/函数名字给个缩写，你让大家猜它是谁/干啥呢？
js 里一个函数有 7、8 个参数，又没类型，光看调用来回切换要花十几分钟，闹呢？
一个函数放好几百行代码，让我来回切换，你是怕我得颈椎病啊？
在一些底层计算出现莫名的数值，不明不白的就加上或减去一个数字，咱也不知道它表达的啥？
if 判断的条件，直接写计算表达式或函数，能有个 4、5 行，每次看这段代码都要花很长时间，还总是出 bug，这不妥妥的"雷区"？
这注释明明写的是 a 逻辑，结果下面代码写的是 b 逻辑，坑啊...
一模一样的代码，复制 n 遍，写这段代码的脑子有坑吧。
一个函数明明写的是 getXXX，结果里面改原始数据？出 bug 找半天，nm。
......

所以，写出整洁的代码就是避免少出现以上出现的情况，可以总结为以下几条：

更具可读性
更节约时间、更高效
更易维护
更具扩展性
更易重用
更容易测试

命名

命名是程序界一级难题

起一个好的名字，至关重要，但并不容易，我常常为了起一个好的名字抓耳挠腮的，有时候跟合作的人会 battle 半天，我们需要建立一个认知： 在长远来看，花费大量时间来选择一个好名字是值得的，因为它所带来的价值或节约的时间远远超过了起名所花费的时间 。

起名字也分几个等级：

最基本的也是见名知意
好一点的可以更恰当的表现业务
再高级一点的可以覆盖领域的概念

有兴趣大家可以看下，《架构师修炼之道》提出对的 7 个阶段，以及如何提炼一个好的名字，下图是之前截的片段

如果要写全关于如何命名我怕是再写上 1000 字也不一定够，所以下面只写一些比较容易做到的，也是最基本的底线：

名字尽可能具体些（不要怕长），少用缩写 ，除非是大家共识的（JDBC、XML）

typescript 复制代码

    // bad
    const act = 1; // 不清楚是 active 还是 action
    function recursion() {}; // 只知道递归，但是不知道为什么要递归

    // good
    const action = 10;
    function getAllChildrenByNodes() {}

尽可能起一些简单的单词，最好能读出来，能写出来，容易记住的常规单词 ，想象一下，同事之间讨论读不出来这个单词的尴尬场景，记得之前做的一个商城项目，同事在设计表的时候用了一个单词 integration ，这个单词的本意是数学中的积分，而业务中实际上表达用户积分。这里有一份软件开发常用词汇表：这里
变量用名词或形容词 + 名词，函数名用动词 + 名词或动词 + 形容词 + 名词，类名用名词

typescript 复制代码

    function calculateTotalPrice(){} // 计算总价
    function validateUserPermission(){} // 验证用户权限
    const customerName = "zhangsan"; // 客户姓名
    const recentOrders = [] // 最近的订单
    class PermissionBuilder() {} // 权限构造器

布尔值或函数用 is 或 has 开头，能优先用肯定，不要用否定，更不要用双重否定表示肯定 ，这很不高效

typescript 复制代码

    // bad
    isNotVisible = true;
    // good
    isVisible = false;
    // bad
    isNotInvisible = true; // 不是不可见的，表示可见的
    // good
    isVisible = true;

函数

函数尽可能的短小 ，有兴趣看一些知名函数编程的库： Lodash 。
参数尽可能的少 ，最佳状态是没有参数，其次是 1 个、2 个、3 个，理论上最好不要超过 3 个，不过具体还是要根据实际场景，有些情况下也难以避免。
遵循单一原则，一个函数只做一件事 。一个判断的小技巧：尝试想象对一个函数做单元测试，每可以测的一点就可以罗列一个函数。
参数最好不用布尔值，在参数多的情况最好使用对象代替 ，因为每次调用时都需要看一下原函数的参数是什么，顺序也要对照好，扩展也不方便，会越来越长。示例：

typescript 复制代码

    function getUsersByIds(ids: string[], isDeleted?: boolean, isArchived?: boolean){}
    getUsersByIds([], true, true);
    // good
    function getUsersByIds(ids, options: {isDeleted?: boolean, isArchived?: boolean}) {}
    getUsersByIds([], { isDeleted: true, isArchived: true})

函数尽可能不要依赖上下文 ，这点可以按照纯函数原则。
函数名、签名和函数逻辑和返回值必须保持一致， 挂羊头卖狗肉的行为非常可气，误导比读不懂代码更可怕，比如：

typescript 复制代码

    // 这个函数本意只是验证用户名是否合法，结果内部却包含修改用户信息的逻辑
    function verfiyUserName(user) {
      const regexp = /^[a-zA-Z0-9_-]{3,16}$/;
      if(regexp.test(user.name)) {
    	user.name = 'legal_' + user.name;
        return true;
      } else {
      	return false;
      }
    }
    const user = {id: 1, name: 'zhangsan' };
    const result = verfiyUserName();

函数不要产生副作用，尽可能不要改变原数据或上下文数据，使用不可变数据（Immutable Data） ，js 中也有一些让人诟病的原生函数，比如 sort、reverse、splice 等 ， 可以 filter 、map 或解构代替

typescript 复制代码

    const users = [
      {id: 2, name: '张三'},
      {id: 1, name: '李四'},
      {id: 3, name: '王五'}
    ];
    // 从用户列表中删除名字是王五的元素
    const newUsers = users.filter(x=> x.name !=='王五');
    // 按照 id 排序
    const newUsers = [...users].sort((a, b) => a.id - b.id);