可读性的重要性

  编程有很大一部分时间是在阅读代码，不仅要阅读自己的代码，而且要阅读别人的代码。因此，可读性良好的代码能够大大提高编程效率。
  可读性良好的代码往往会让代码架构更好，因为程序员更愿意去修改这部分代码，而且也更容易修改。
  只有在核心领域为了效率才可以放弃可读性，否则可读性是第一位的。

用名字表示代码含义

一些比较有表达力的单词：

  使用 i、j、k 作为循环迭代器的名字过于简单，user_i、member_i 这种名字会更有表达力。因为循环层次越多，代码越难理解，有表达力的迭代器名字可读性会更高。
  为名字添加形容词等信息能让名字更具有表达力，但是名字也会变长。名字长短的准则是：作用域越大，名字越长。因此只有在短作用域才能使用一些简单名字。

名字不能带来歧义

  起完名字要思考一下别人会对这个名字有何解读，会不会误解了原本想表达的含义。
布尔相关的命名加上 is、can、should、has等前缀。
用 min、max 表示数量范围；
用 first、last 表示访问空间的包含范围；

begin、end 表示访问空间的排除范围，即 end 不包含尾部。

良好的代码风格

适当的空行和缩进。
排列整齐的注释：

int a = 1;   // 注释
int b = 11;  // 注释
int c = 111; // 注释

语句顺序不能随意，比如与 html 表单相关联的变量的赋值应该和表单在 html 中的顺序一致。

为何需要注释

  阅读代码首先会注意到注释，如果注释没太大作用，那么就会浪费代码阅读的时间。那些能直接看出含义的代码不需要写注释，特别是不需要为每个方法都加上注释，比如那些简单的 getter 和 setter 方法，为这些方法写注释反而让代码可读性更差。
  不能因为有注释就随便起个名字，而是争取起个好名字而不写注释。
  可以用注释来记录采用当前解决办法的思考过程，从而让读者更容易理解代码。
  注释用来提醒一些特殊情况。
用 TODO 等做标记：

如何编写注释

尽量简洁明了

// The first String is student's name
// The Second Integer is student's score
Map<String, Integer> scoreMap = new HashMap<>();

// Student's name -> Student's score
Map<String, Integer> scoreMap = new HashMap<>();

添加测试用例来说明：

// ...
// Example: add(1, 2), return 3
int add(int x, int y) {
    return x + y;
}

使用专业名词来缩短概念上的解释，比如用设计模式名来说明代码。

提高控制流的可读性

条件表达式中，左侧是变量，右侧是常数。比如下面第一个语句正确：

if (len < 10)
if (10 > len)

只有在逻辑简单的情况下使用 ? : 三目运算符来使代码更紧凑，否则应该拆分成 if / else；
do / while 的条件放在后面，不够简单明了，并且会有一些迷惑的地方，最好使用 while 来代替。
如果只有一个 goto 目标，那么 goto 尚且还能接受，但是过于复杂的 goto 会让代码可读性特别差，应该避免使用 goto。
在嵌套的循环中，用一些 return 语句往往能减少嵌套的层数。

拆分长表达式

长表达式的可读性很差，可以引入一些解释变量从而拆分表达式：

if line.split(':')[0].strip() == "root":
    ...
username = line.split(':')[0].strip()
if username == "root":
    ...

使用摩根定理简化一些逻辑表达式：

if (!a && !b) {
    ...
}
if (!(a || b)) {
    ...
}

变量与可读性

去除控制流变量 。在循环中通过使用 break 或者 return 可以减少控制流变量的使用。

boolean done = false;
while (/* condition */ && !done) {
    ...
    if ( ... ) {
        done = true;
        continue;
    }
}
while(/* condition */) {
    ...
    if ( ... ) {
        break;
    }
}

减小变量作用域 。作用域越小，越容易定位到变量所有使用的地方。

JavaScript 可以用闭包减小作用域。以下代码中 submit_form 是函数变量，submitted 变量控制函数不会被提交两次。第一个实现中 submitted 是全局变量，第二个实现把 submitted 放到匿名函数中，从而限制了起作用域范围。

submitted = false;
var submit_form = function(form_name) {
    if (submitted) {
        return;
    }
    submitted = true;
};
var submit_form = (function() {
    var submitted = false;
    return function(form_name) {
        if(submitted) {
            return;
        }
        submitted = true;
    }
}());  // () 使得外层匿名函数立即执行

JavaScript 中没有用 var 声明的变量都是全局变量，而全局变量很容易造成迷惑，因此应当总是用 var 来声明变量。
变量定义的位置应当离它使用的位置最近。
实例解析
在一个网页中有以下文本输入字段：

<input type = "text" id = "input1" value = "a">
<input type = "text" id = "input2" value = "b">
<input type = "text" id = "input3" value = "">
<input type = "text" id = "input4" value = "d">

现在要接受一个字符串并把它放到第一个空的 input 字段中，初始实现如下：

var setFirstEmptyInput = function(new_alue) {
    var found = false;
    var i = 1;
    var elem = document.getElementById('input' + i);
    while (elem != null) {
        if (elem.value === '') {
            found = true;
            break;
        }
        i++;
        elem = document.getElementById('input' + i);
    }
    if (found) elem.value = new_value;
    return elem;
}

以上实现有以下问题：

found 可以去除；
elem 作用域过大；
可以用 for 循环代替 while 循环；

var setFirstEmptyInput = function(new_value) {
    for (var i = 1; true; i++) {
        var elem = document.getElementById('input' + i);
        if (elem === null) {
            return null;
        }
        if (elem.value === '') {
            elem.value = new_value;
            return elem;
        }
    }
};

抽取函数

  工程学就是把大问题拆分成小问题再把这些问题的解决方案放回一起。
  首先应该明确一个函数的高层次目标，然后对于不是直接为了这个目标工作的代码，抽取出来放到独立的函数中。
介绍性的代码：

int findClostElement(int[] arr) {
    int clostIdx;
    int clostDist = Interger.MAX_VALUE;
    for (int i = 0; i < arr.length; i++) {
        int x = ...;
        int y = ...;
        int z = ...;
        int value = x * y * z;
        int dist = Math.sqrt(Math.pow(value, 2), Math.pow(arr[i], 2));
        if (dist < clostDist) {
            clostIdx = i;
            clostDist = value;
        }
    }
    return clostIdx;
}

以上代码中循环部分主要计算距离，这部分不属于代码高层次目标，高层次目标是寻找最小距离的值，因此可以把这部分代替提取到独立的函数中。这样做也带来一个额外的好处有：可以单独进行测试、可以快速找到程序错误并修改。

public int findClostElement(int[] arr) {
    int clostIdx;
    int clostDist = Interger.MAX_VALUE;
    for (int i = 0; i < arr.length; i++) {
        int dist = computDist(arr, i);
        if (dist < clostDist) {
            clostIdx = i;
            clostDist = value;
        }
    }
    return clostIdx;
}

并不是函数抽取的越多越好，如果抽取过多，在阅读代码的时候可能需要不断跳来跳去。只有在当前函数不需要去了解某一块代码细节而能够表达其内容时，把这块代码抽取成子函数才是好的。
函数抽取也利于减小代码的冗余。

一次只做一件事

只做一件事的代码很容易让人知道其要做的事；
基本流程：
列出代码所做的所有任务；
把每个任务拆分到不同的函数，或者不同的段落。

用自然语言表述代码

先用自然语言书写代码逻辑，也就是伪代码，然后再写代码，这样代码逻辑会更清晰。

减少代码量

不要过度设计，编码过程会有很多变化，过度设计的内容到最后往往是无用的。
多用标准库实现。

• 一、可读性的重要性
• 二、用名字表达代码含义
• 三、名字不能带来歧义
• 四、良好的代码风格
• 五、为何编写注释
• 六、如何编写注释
• 七、提高控制流的可读性
• 八、拆分长表达式
• 九、变量与可读性
• 十、抽取函数
• 十一、一次只做一件事
• 十二、用自然语言表述代码
• 十三、减少代码量
• 参考资料

一、可读性的重要性

编程有很大一部分时间是在阅读代码，不仅要阅读自己的代码，而且要阅读别人的代码。因此，可读性良好的代码能够大大提高编程效率。

可读性良好的代码往往会让代码架构更好，因为程序员更愿意去修改这部分代码，而且也更容易修改。

只有在核心领域为了效率才可以放弃可读性，否则可读性是第一位。

二、用名字表达代码含义

一些比较有表达力的单词：

使用 i、j、k 作为循环迭代器的名字过于简单，user_i、member_i 这种名字会更有表达力。因为循环层次越多，代码越难理解，有表达力的迭代器名字可读性会更高。

为名字添加形容词等信息能让名字更具有表达力，但是名字也会变长。名字长短的准则是：作用域越大，名字越长。因此只有在短作用域才能使用一些简单名字。

三、名字不能带来歧义

起完名字要思考一下别人会对这个名字有何解读，会不会误解了原本想表达的含义。

布尔相关的命名加上 is、can、should、has 等前缀。

• 用 min、max 表示数量范围；
• 用 first、last 表示访问空间的包含范围；
• begin、end 表示访问空间的排除范围，即 end 不包含尾部。

四、良好的代码风格

适当的空行和缩进。

排列整齐的注释：

int a = 1;   // 注释
int b = 11;  // 注释
int c = 111; // 注释

语句顺序不能随意，比如与 html 表单相关联的变量的赋值应该和表单在 html 中的顺序一致。

五、为何编写注释

阅读代码首先会注意到注释，如果注释没太大作用，那么就会浪费代码阅读的时间。那些能直接看出含义的代码不需要写注释，特别是并不需要为每个方法都加上注释，比如那些简单的 getter 和 setter 方法，为这些方法写注释反而让代码可读性更差。

不能因为有注释就随便起个名字，而是争取起个好名字而不写注释。

可以用注释来记录采用当前解决办法的思考过程，从而让读者更容易理解代码。

注释用来提醒一些特殊情况。

用 TODO 等做标记：

六、如何编写注释

尽量简洁明了：

// The first String is student's name
// The Second Integer is student's score
Map<String, Integer> scoreMap = new HashMap<>();

// Student's name -> Student's score
Map<String, Integer> scoreMap = new HashMap<>();

添加测试用例来说明：

// ...
// Example: add(1, 2), return 3
int add(int x, int y) {
    return x + y;
}

使用专业名词来缩短概念上的解释，比如用设计模式名来说明代码。

七、提高控制流的可读性

条件表达式中，左侧是变量，右侧是常数。比如下面第一个语句正确：

if (len < 10)
if (10 > len)

只有在逻辑简单的情况下使用 ? : 三目运算符来使代码更紧凑，否则应该拆分成 if / else；

do / while 的条件放在后面，不够简单明了，并且会有一些迷惑的地方，最好使用 while 来代替。

如果只有一个 goto 目标，那么 goto 尚且还能接受，但是过于复杂的 goto 会让代码可读性特别差，应该避免使用 goto。

在嵌套的循环中，用一些 return 语句往往能减少嵌套的层数。

八、拆分长表达式

长表达式的可读性很差，可以引入一些解释变量从而拆分表达式：

if line.split(':')[0].strip() == "root":
    ...

username = line.split(':')[0].strip()
if username == "root":
    ...

使用摩根定理简化一些逻辑表达式：

if (!a && !b) {
    ...
}

if (!(a || b)) {
    ...
}

九、变量与可读性

去除控制流变量 。在循环中通过使用 break 或者 return 可以减少控制流变量的使用。

boolean done = false;
while (/* condition */ && !done) {
    ...
    if ( ... ) {
        done = true;
        continue;
    }
}

while(/* condition */) {
    ...
    if ( ... ) {
        break;
    }
}

减小变量作用域 。作用域越小，越容易定位到变量所有使用的地方。

JavaScript 可以用闭包减小作用域。以下代码中 submit_form 是函数变量，submitted 变量控制函数不会被提交两次。第一个实现中 submitted 是全局变量，第二个实现把 submitted 放到匿名函数中，从而限制了起作用域范围。

submitted = false;
var submit_form = function(form_name) {
    if (submitted) {
        return;
    }
    submitted = true;
};

var submit_form = (function() {
    var submitted = false;
    return function(form_name) {
        if(submitted) {
            return;
        }
        submitted = true;
    }
}());  // () 使得外层匿名函数立即执行

JavaScript 中没有用 var 声明的变量都是全局变量，而全局变量很容易造成迷惑，因此应当总是用 var 来声明变量。

变量定义的位置应当离它使用的位置最近。

实例解析

在一个网页中有以下文本输入字段：

<input type = "text" id = "input1" value = "a">
<input type = "text" id = "input2" value = "b">
<input type = "text" id = "input3" value = "">
<input type = "text" id = "input4" value = "d">

现在要接受一个字符串并把它放到第一个空的 input 字段中，初始实现如下：

var setFirstEmptyInput = function(new_alue) {
    var found = false;
    var i = 1;
    var elem = document.getElementById('input' + i);
    while (elem != null) {
        if (elem.value === '') {
            found = true;
            break;
        }
        i++;
        elem = document.getElementById('input' + i);
    }
    if (found) elem.value = new_value;
    return elem;
}

以上实现有以下问题：

• found 可以去除；
• elem 作用域过大；
• 可以用 for 循环代替 while 循环；

var setFirstEmptyInput = function(new_value) {
    for (var i = 1; true; i++) {
        var elem = document.getElementById('input' + i);
        if (elem === null) {
            return null;
        }
        if (elem.value === '') {
            elem.value = new_value;
            return elem;
        }
    }
};

十、抽取函数

工程学就是把大问题拆分成小问题再把这些问题的解决方案放回一起。

首先应该明确一个函数的高层次目标，然后对于不是直接为了这个目标工作的代码，抽取出来放到独立的函数中。

介绍性的代码：

int findClostElement(int[] arr) {
    int clostIdx;
    int clostDist = Interger.MAX_VALUE;
    for (int i = 0; i < arr.length; i++) {
        int x = ...;
        int y = ...;
        int z = ...;
        int value = x * y * z;
        int dist = Math.sqrt(Math.pow(value, 2), Math.pow(arr[i], 2));
        if (dist < clostDist) {
            clostIdx = i;
            clostDist = value;
        }
    }
    return clostIdx;
}

以上代码中循环部分主要计算距离，这部分不属于代码高层次目标，高层次目标是寻找最小距离的值，因此可以把这部分代替提取到独立的函数中。这样做也带来一个额外的好处有：可以单独进行测试、可以快速找到程序错误并修改。

public int findClostElement(int[] arr) {
    int clostIdx;
    int clostDist = Interger.MAX_VALUE;
    for (int i = 0; i < arr.length; i++) {
        int dist = computDist(arr, i);
        if (dist < clostDist) {
            clostIdx = i;
            clostDist = value;
        }
    }
    return clostIdx;
}

并不是函数抽取的越多越好，如果抽取过多，在阅读代码的时候可能需要不断跳来跳去。只有在当前函数不需要去了解某一块代码细节而能够表达其内容时，把这块代码抽取成子函数才是好的。

函数抽取也用于减小代码的冗余。

十一、一次只做一件事

只做一件事的代码很容易让人知道其要做的事；

基本流程：列出代码所做的所有任务；把每个任务拆分到不同的函数，或者不同的段落。

十二、用自然语言表述代码

先用自然语言书写代码逻辑，也就是伪代码，然后再写代码，这样代码逻辑会更清晰。

十三、减少代码量

不要过度设计，编码过程会有很多变化，过度设计的内容到最后往往是无用的。

多用标准库实现。

参考资料

• Dustin, Boswell, Trevor, 等. 编写可读代码的艺术 [M]. 机械工业出版社, 2012.

嵌入式处理器发展到今天，速度已经很可观了。而产品的快速迭代，要求技术积累和技术细分，代码可继承性，即“可读性”的要求会越来越高。

易读！易读！易读！！

倘若对自己代码有要求，你会发现，它几乎是最重要的。神眼中的“优雅”，可能就蕴含在这里面。

关于如何写出可读性强的代码，有很多好书值得详细阅读，《C专家编程》、《代码大全》、《编程珠玑》，等等。这个课题很大，我只讲一些个人的心路历程：

代码1

uint32_t acf_tsk(uint64_t time_us)
{
  ACF_POOL.acf1_rxBit = GPIO_ReadInputDataBit(ACF_RX_GPIO_PORT, ACF_RX_PIN);
  
  if (ACF_POOL.acf_rxBit){ ACFAI_POOL.acf_timeTmp = time_us;
                           ACFAI_POOL.acf_errFlg = ACF_FLG_F;
  }else{
    if ((ACF_POOL.acf_timeTmp + ACF_OT_TIME_US)<= time_us) ACF_POOL.acf_errFlg = ACF_FLG_T;
    else                                                   ACF_POOL.acf_errFlg = ACF_FLG_F;
  }
  
  return 0;
}

应该能看出作者想让“代码越集中越好”的企图，目的是实现“一个函数的内容在同一帧屏幕中显示，尽量减少鼠标滚轴操作”。这个函数很短，所以看不到效果。碰到大函数，又不好拆分成几个函数时，会更想这么干。

代码2：

uint32_t acf_tsk(uint64_t time_us)
{
  ACF_POOL.acf1_rxBit = GPIO_ReadInputDataBit(ACF_RX_GPIO_PORT, ACF_RX_PIN);
  
  if (ACF_POOL.acf_rxBit){
    ACFAI_POOL.acf_timeTmp = time_us;
    ACFAI_POOL.acf_errFlg = ACF_FLG_F;
  }else{
    if ((ACF_POOL.acf_timeTmp + ACF_OT_TIME_US)<= time_us){
      ACF_POOL.acf_errFlg = ACF_FLG_T;
    }else{
      ACF_POOL.acf_errFlg = ACF_FLG_F;
    }
  }
  
  return 0;
}

作者注意到了代码过分集中可能会影响排版，导致不同编辑环境下排版混乱。以及if分支最好带括号等等，看起来听进了前辈的谆谆教诲。

代码3：

uint32_t acf_tsk(uint64_t time_us)
{
  ACF_POOL.acf1_rxBit = GPIO_ReadInputDataBit(ACF_RX_GPIO_PORT, ACF_RX_PIN);
  
  if (ACF_POOL.acf_rxBit)
  {
    ACFAI_POOL.acf_timeTmp = time_us;
    ACFAI_POOL.acf_errFlg = ACF_FLG_F;
  }
  else
  {
    if ((ACF_POOL.acf_timeTmp + ACF_OT_TIME_US)<=time_us)
    {
      ACF_POOL.acf_errFlg = ACF_FLG_T;
    }
    else
    {
      ACF_POOL.acf_errFlg = ACF_FLG_F;
    }
  }
  
  return 0;
}

作者终于意识到，代码不是越集中越好，符合规范的结构，比如让大括号单独成行，反而看起来更加清晰、舒服，是更能避免笔误的好习惯。

代码4：

uint32_t acf_tsk(uint64_t time_us)
{
    ACF_POOL.acf1_rxBit = GPIO_ReadInputDataBit(ACF_RX_GPIO_PORT, ACF_RX_PIN);
    
    if (ACF_POOL.acf_rxBit)
    {
        ACFAI_POOL.acf_timeTmp = time_us;
        ACFAI_POOL.acf_errFlg = ACF_FLG_F;
    }
    else
    {
        if ((ACF_POOL.acf_timeTmp + ACF_OT_TIME_US)
            <= time_us)
        {
            ACF_POOL.acf_errFlg = ACF_FLG_T;
        }
        else
        {
            ACF_POOL.acf_errFlg = ACF_FLG_F;
        }
    }
    
    return 0;
}

作者注意到缩进的问题，即到底是用Tab键缩进，还是用空格键缩进。不统一就会带来混乱，换个编辑环境，这类问题很容易暴露，会极大影响阅读心情。我后来将keil编辑器的Tab键配置成了4个空格键，并且养成了缩进4个空格的习惯。

代码5：

uint32_t acf_tsk(uint64_t time_us)
{
    /* Get ACF RX pin. */
    ACF_POOL.acf1_rxBit = GPIO_ReadInputDataBit(ACF_RX_GPIO_PORT, ACF_RX_PIN);
    
    /* ACF error flag filter. */
    if (ACF_POOL.acf_rxBit)
    {
        /* ACF bit is right.*/
        ACFAI_POOL.acf_timeTmp = time_us;
        ACFAI_POOL.acf_errFlg = ACF_FLG_F;
    }
    else
    {
        /* ACF bit is wrong.*/
        if ((ACF_POOL.acf_timeTmp + ACF_OT_TIME_US)
            <= time_us)
        {
            ACF_POOL.acf_errFlg = ACF_FLG_T;
        }
        else
        {
            ACF_POOL.acf_errFlg = ACF_FLG_F;
        }
    }
    
    return 0;
}

作者突然想到，既然要增强可读性，那么加一些注释吧。于是就加了一些，并且不是很过分，还好。

总结：

代码1到代码5，代码内容是一模一样的，执行效果完全相同，但是可读性完全不同，是逐渐变得“优雅”起来的。这反映了近一年的时间里，我编写嵌入式代码的心路历程，也是逐渐养成编程好习惯的过程。

其实代码5的层次要在代码4之下。因为对于高手来说，应尽量减少注释，通过代码“自表性”来保证代码易读性。神说，自表性好的代码，就像美文一样。不过我辈功力不够，加一些注释来提高可读性还是必要的。不过，如果注释过多，那就说明代码本身需要好好设计一下了。

虽然，代码可读性是通过设计来实现的，但是其更加强有力的保障来自好的编程习惯。

身边有前辈说，看一个人的功力，那就搭眼看一下他的代码，立马就能判断出来，不用看细节。

简单记录一下成长轨迹，希望将来回头看这篇文章，会觉得自己好幼稚。