代码整洁之道gitbook

代码整洁之道

[toc]

第一章

1. 开篇第一句话我认为最符合本书主题：“阅读本书有两种原因：第一，你是一个程序员；第二，你想成为更好的程序员。”
2. “勒布朗法则：稍后等于永不（Later equals never）”。 这句话在我的印象里确实说过 ‘：先这样吧，以后有时间在弄’，然后以后可能在也没弄过了。

第二章

1. “变量、函数或类的名称应该已经答复了所有的大问题。它该告诉你，它为什么会存在，它做什么事，应该怎么用。如果名称需要注释来补充，那就不算是名副其实。” 也就是说，应该使用有意义的名称（驼峰命名法）来 ‘描述’ 它们。
2. 做有意义的区分，如果有一个productInfo和productData的类，虽然他们名字不同，但是表示的意思确无区别。
3. 类名和对象名应该是名词或名词短语，例如：Customer、 WikiPage、Account 或 AddressParser。应该避免使用 Manager、Processor 、 Data 或 Info 这样的类名。类名不应当是动词。
4. 方法名应当是动词或动词短语，如 postPayMent 、 deletePage 或 save 。
5. 给每个抽象概念选一个词，并且一以贯之。例如，使用 fetch 、 retrieve 和 get 来给多个类中的同种方法命名。
6. 避免将同一单词用于不同目的。
7. 代码作者应尽力写出易于理解的代码。应该把代码写的一目了然，而不必让别人禅精竭虑的研究。

第三章

1. 函数的第一条规则就是要短小。第二条规则是还要更短小。
2. “函数应该做一件事。做好这件事。只做这一件事。” 做好函数拆分非常重要，不仅结构清晰，而且利于函数复用。
3. 不要害怕长名称。长而具有描述性的名称，要比短而令人费解的名称好。长而具有描述性的名称，要比描述性的长注释好。
4. 最理想的函数数量是 0 个，其次是 1 个，再次是 2 个，应该尽量避免 3 个参数。
5. 最好把 try / catch 代码块的主体部分抽离出来，另外形成函数。

第四章

1. 什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。
2. 有些注释掉的代码，其实可以都删掉。
3. 总的来说，就是只写必要的注释，能够清晰描述的注释。

第五章

1. 合理的使用空白行分隔代码，能够使代码结构更加清晰，可读性大大增强。
2. 在赋值操作符 “=” 的两侧加空格，以达到强调的目的。 let a = 1
3. 不需要在函数名和左元括号之间加空格，因为函数和其参数密切相关，如果隔开，就显得互无关系。
4. 函数中的参数需要用逗号隔开，表示参数是互相分离的。
5. 乘法 “*” 之间没加空格，因为乘法具有较高的优先级。 加法和减法之间需要加空格，因为加法和减法的优先级较低。

第七章

1. 我们可以使用 try/catch/finally 来捕获错误和抛出错误。

2. 抛出的每个异常，都应当提供足够的环境说明，以判断错误信息的来源和位置。同时应创建信息充分的错误消息，并和异常一起传递出去，在消息中，应包括失败的操作和失败的类型。

第八章

1. “如果有良好的软件设计，则无须巨大投入和重写即可进行修改”。 这就表示期初项目设计封装的重要性。
2. 单元测试能够让你的代码可扩展、可维护和可复用。因为有了测试，就不用担心对代码的修改。没有测试，每次修改都有可能带来缺陷。
3. 一个测试一个断言。或者可以说，单个测试中的断言数量应该最小化。
4. 整洁的测试包含以下 5 条规则：
   • 快速。测试应该够快，能够快速运行。
   • 独立。每个测试应该相互独立。
   • 可重复。测试应当可以在任何环境中重复使用。
   • 自足验证。测试应当有布尔值输出。
   • 及时。测试应当及时编写。

第十二章

1. 只要遵循以下规则，设计就能变得“简单”：
   • 运行所有测试
   • 不可重复
   • 表达了程序员的意图
   • 尽可能减少类和方法的数量
2. 有了测试，就能保持代码的整洁，方法就是递增式地重构代码。测试消除了对清理代码就会破坏代码的恐惧。

第十四章

1. “编程是一种技艺甚于科学的东西。要编写整洁代码，必须先写肮脏的代码，然后再清理它。”
2. “就像写作文一样，应该先写草稿，在写二稿，一次又一次地撰稿，最后写出终稿。写出好作文是一个逐步改进的过程。”
3. “多数新手程序员没有特别认真地遵守这个建议。他们相信，首要任务是写出能工作的程序。只要程序能工作，就转移到下一个任务上，而那个能工作的程序就留在了最后那个所谓能工作的转态。多数有经验的程序员都知道，这是一种自毁行为。”

代码整洁之道

官网：https://haomo-tech.com

作者：毫末科技

邮箱：

概述

本章节主要目的是为了规范代码编写过程中的几个标准，防止写出难以维护和修改的代码。

定义

糟糕的代码（简笔画）

• 编写过程没有构思，从头写到尾

• 命名混乱

• 缺乏注释信息

• 代码臃肿

• 公共方法和组件没有抽离

• 核心逻辑无法测试

整洁的代码（素描）

• 编写过程有构思，以点到面

• 命名干净整洁

• 提供信息类注释

• 代码短小精悍

• 公共部分能很好的抽离

• 核心逻辑通过测试用例保证代码质量

必要性

写出糟糕代码的原因：

• 任务时间评估有偏差，为了赶时间不顾代码质量

• 没有养成编写整洁代码的方法和习惯

• ......

项目经理是进度和需求的守护者，程序员是代码质量的守护者。

面对项目经理的压力，我们应该如实告诉项目经理任务中遇到的问题以及导致任务时间偏差的原因，而不是逃避问题并制造混乱。写出整洁的代码，守护住代码的质量是程序员专业性的体现。

糟糕的代码难以维护和修改，会严重拖累项目的质量进度。

方法

有意义的命名

• 避免无意义的命名，例如a、b、c，使用他人可以读懂的命名
• 使用读的出来的名称，addUser
• 避免误导，例如userIdList为String[]类型而非List类型，应该取名为userIds
• 命名应该为动词+名词或名词

示例：

设计云组件ID命名：动词(操作)+名词(表名+（字段名）+组件名)

https://dev.block-design.cn/edit-page/?pageId=1417653844220841986

示例

添加用户按钮（addSysUserButton）、用户表格（sysUserTable）、添加用户名称输入框（addSysUserNameInput）

函数

• 短小，每个函数只说一件事

• 函数参数保证在三个以内，越少越好

示例：

function() {
  // 加载系统所有的角色
  let url = 'http://ckjd.dev.haomo-tech.com/api/sys/role/list';
  this.$getAction(url).then(res => {
    console.log('加载系统所有角色：', res);
    this.allRoles = res.result.records;
    this.newRolename.options = this.allRoles.map(role => {
      return {
        label: role.roleName,
        value: role.id
      }
    });
    this.editRolename.options = this.allRoles.map(role => {
      return {
        label: role.roleName,
        value: role.id
      }
    });
    console.log('加载系统所有角色1：', this.newRolename);
  })
}

重构后：

function() {
  // 获取角色信息
  this.getRoles = function(){
      let url = 'http://ckjd.dev.haomo-tech.com/api/sys/role/list';
    this.$getAction(url).then(res => {
      this.setRoles(res.result.records);
    })
  };
  // 渲染角色信息
  this.setRoles = function(roles){
    let roleOptions = this.transformRolesToOptions(roles);
    this.newRolename.options = roleOptions;
    this.editRolename.options = roleOptions;
  };
  // 转化角色信息为配置项信息
  this.transformRolesToOptions = function(roles){
    return roles.map(role => {return {label: role.roleName, value: role.id}});
  }

  this.getRoles();
}

注释

• 尽量使用整洁的代码进行解释，而非使用注释
• 编写信息类注释，例如函数注释（参数、返回值的类型和解释）、对意图的解释、TODO注释

格式

• 代码编写完通过格式化工具进行格式化处理
• 缩进应该使用两个空格

边界

• 学习型测试第三方工具，使用测试用例来对第三方工具进行学习

单元测试

• 核心逻辑使用TDD测试驱动开发，先编写测试用例和断言，再编写代码实现来通过测试，再对代码进行重构
• 每个测试用例对应一个断言

规范

1. 组件ID命名：动词(操作)+名词(表名+（字段名）+组件名)
2. 函数不应超过20行，参数不超过三个
3. 代码需要格式化处理，缩进两个空格
4. 核心逻辑使用测试用例驱动开发

参考

• 代码整洁之道