在《如何编写合格代码》的上篇中的开头，我给大家分享了对于“合格的代码” 的定义。

在本文的开头，不妨先让大家重温一下：

• 满足要求定义的初始化规则
• 代码清晰简洁，没有思维逆反的逻辑或者刻意为之的陷阱代码
• 尽可能控制代码风险
• 合理的代码注释
• 合理的标准化接口定义合，杜绝误用或者滥用

关于前三点的具体注意事项和例子，之前已经有所阐述。（有所忘记的读者可以再重读上篇）

接下来，我将会继续阐述剩下的两点守则。

合理的代码注释

当一个经验丰富的工程师第一眼接触到不合格的代码时，就会下意识地有所察觉。而引起这种“不适感”的很大一个可能原因，就是缺乏合理简洁的注释和排版。

我们在编程工作中应该时常会遇到这样的场景：

• 当我们编写一个函数后，发现自己应该为函数名或者变量名额外注释说明。

  -那可能是因为你当初定义的变量和函数名称太过随意和模糊；

• 当我们为函数功能做注释的时候，发觉函数的描述涉及到的功能内容非常多而繁杂。

  -那可能是因为你缺乏架构设计，把太多功能塞在了一个函数里了；

• 当我们洋洋洒洒写下几千行代码后，发现需要大段的注释才能阐述清楚自己写的代码对应的逻辑和功能。

  -那么这段代码基本上十有八九是写得有问题，需要重构；

根据我的开发经验，除非极其简单到一目了然的代码，否则编写完后都必须要养成习惯添加足够的注释。

只有充分的注释，才能让阅读你代码的人能更真切快速了解到函数的功能、输入、输出是什么，有没有副作用和风险等等。这些如果缺乏注释的话，往往需要耗费阅读者很多的时间，浪费很多的精力才能有所重现和领悟，极大降低代码的使用效率。

而在编写注释的过程中，即意味着你需要站在另外一个角度来审视自己的代码。而往往在这个时候，通过编写注释的过程，你会对自己代码不合理的地方有所觉察，进而把自己的代码修正得更完善。

写注释是一门看似最简单，实则高深莫测的学问。无论是格式的定义，描述的语言组织能力，都无不体现着编程人员的专业素养。

代码的接口定义合理

首先我们看什么是接口？

从软件开发的角度看：宏和函数是接口，类和数据结构是接口，库（library）和包（package）是接口，环境变量是接口，消息类型和网络协议是接口，系统调用是接口，软硬中断是接口，EABI 是接口。

所以只要我们在写代码，我们就无时无刻不和接口打交道，也时时刻刻在创建新的接口。

合格的代码的必要条件是有合理的接口。

什么是合理的接口？我认为必须要符合以下的条件

• 合理的名称

  -合理的名称的重要性是不言而喻的，这样才可以让使用接口的人不会产生不解和困惑。

• 合理的输入输出

  -合理的输入输出是指接口不要期待过于复杂的输入（比如函数的参数不宜超过五个），如无必要，不要依赖输入以外的数据，而且输入参数包含的数据只需刚好满足相关的需求即可，不要传入无关紧要的数据；对于输出，和输入的要求类似，不要输出会让调用者感到困惑的结果。

• 符合惯例

  -符合惯例是接口设计中非常重要的原则。比如在有些语言中，size() 按惯例是个 O(1) 的操作，而length() 是 O(n) 的操作。那么你在为你的数据结构提供接口时，也要遵循这个约定，这样使用者才不会困惑，也不会误用。

作为一个优秀的程序员，要时时刻刻为你的代码负责，要时时刻刻为你的接口负责，让用户只能正确地、轻松地使用我们的成果产出。

作为一个合格的程序员，我们应该不断写出合格的，优秀的代码，而不是在这个信息时代中堆砌更加多的数据废物。

让我们一起为成为一名优秀的程序员而努力。

想要学习更多的程序员技巧，请继续关注后续的连载文章。