在《如何编写合格代码》的上篇中的开头,我给大家分享了对于“合格的代码” 的定义。
在本文的开头,不妨先让大家重温一下:
- 满足要求定义的初始化规则 - 代码清晰简洁,没有思维逆反的逻辑或者刻意为之的陷阱代码 - 尽可能控制代码风险 - 合理的代码注释 - 合理的标准化接口定义合,杜绝误用或者滥用
关于前三点的具体注意事项和例子,之前已经有所阐述。(有所忘记的读者可以再重读上篇)
接下来,我将会继续阐述剩下的两点守则。
合理的代码注释
当一个经验丰富的工程师第一眼接触到不合格的代码时,就会下意识地有所察觉。而引起这种“不适感”的很大一个可能原因,就是缺乏合理简洁的注释和排版。
我们在编程工作中应该时常会遇到这样的场景:
- 当我们编写一个函数后,发现自己应该为函数名或者变量名额外注释说明。
-那可能是因为你当初定义的变量和函数名称太过随意和模糊;
- 当我们为函数功能做注释的时候,发觉函数的描述涉及到的功能内容非常多而繁杂。
-那可能是因为你缺乏架构设计,把太多功能塞在了一个函数里了;
- 当我们洋洋洒洒写下几千行代码后,发现需要大段的注释才能阐述清楚自己写的代码对应的逻辑和功能。
-那么这段代码基本上十有八九是写得有问题,需要重构;
根据我的开发经验,除非极其简单到一目了然的代码,否则编写完后都必须要养成习惯添加足够的注释。
只有充分的注释,才能让阅读你代码的人能更真切快速了解到函数的功能、输入、输出是什么,有没有副作用和风险等等。这些如果缺乏注释的话,往往需要耗费阅读者很多的时间,浪费很多的精力才能有所重现和领悟,极大降低代码的使用效率。
而在编写注释的过程中,即意味着你需要站在另外一个角度来审视自己的代码。而往往在这个时候,通过编写注释的过程,你会对自己代码不合理的地方有所觉察,进而把自己的代码修正得更完善。
写注释是一门看似最简单,实则高深莫测的学问。无论是格式的定义,描述的语言组织能力,都无不体现着编程人员的专业素养。
代码的接口定义合理
首先我们看什么是接口?
从软件开发的角度看:宏和函数是接口,类和数据结构是接口,库(library)和包(package)是接口,环境变量是接口,消息类型和网络协议是接口,系统调用是接口,软硬中断是接口,EABI 是接口。
所以只要我们在写代码,我们就无时无刻不和接口打交道,也时时刻刻在创建新的接口。
合格的代码的必要条件是有合理的接口。
什么是合理的接口?我认为必须要符合以下的条件
- 合理的名称
-合理的名称的重要性是不言而喻的,这样才可以让使用接口的人不会产生不解和困惑。
- 合理的输入输出 -合理的输入输出是指接口不要期待过于复杂的输入(比如函数的参数不宜超过五个),如无必要,不要依赖输入以外的数据,而且输入参数包含的数据只需刚好满足相关的需求即可,不要传入无关紧要的数据;对于输出,和输入的要求类似,不要输出会让调用者感到困惑的结果。
- 符合惯例
-符合惯例是接口设计中非常重要的原则。比如在有些语言中,size() 按惯例是个 O(1) 的操作,而length() 是 O(n) 的操作。那么你在为你的数据结构提供接口时,也要遵循这个约定,这样使用者才不会困惑,也不会误用。
作为一个优秀的程序员,要时时刻刻为你的代码负责,要时时刻刻为你的接口负责,让用户只能正确地、轻松地使用我们的成果产出。
作为一个合格的程序员,我们应该不断写出合格的,优秀的代码,而不是在这个信息时代中堆砌更加多的数据废物。
让我们一起为成为一名优秀的程序员而努力。
想要学习更多的程序员技巧,请继续关注后续的连载文章。
由睿江云人员提供,想了解更多,请登陆www.eflycloud.com