编码规范一些建议

Posted by 周思进 on February 1, 2020

一、编写直观易读的代码

不要一味追求代码简短,或者使用一些不怎么好理解的技巧性代码。编写直观易读的代码对于他人阅读理解代码及代码审核上都会省时又省力,同时也能降低不必要的代码错误可能性。

二、有充分的注释

在整个代码文件开头,需要有该代码文件相关说明,让阅读者大概知道这个代码文件里的代码主要是干啥的,还有文件的版权声明。

每个函数声明都需要有明确的函数功能说明,各个入参、出参代表的含义及对应值的范围,还有函数所有可能的返回值情况说明等等,保证调用者看你的函数说明不看具体实现就能清楚如何使用该接口函数。
如果接口存在依赖关系的,也要明确说明依赖关系,哪个先调用,哪个后调用。

对于函数里执行的代码,只要让别人看了这行代码,心中有疑惑,不清楚这么做的原因,你就应该增加注释说明下,基本只要代码审核的时候,对方问你这代码是在干啥,基本是需要加上注释了。
比如代码里常见的一些sleep操作,也不知道为啥要sleep个几秒,不加注释,根本不知道是出于什么考虑做的。

处理的一些bug解决,为什么这样改动,有必要的话也增加注释说明,否则你会发现一段时间过去再回头看可能都不知道当初是为了解决什么问题而这样修改的。

三、命名规范

包括变量命名、函数命名、代码文件命名。 变量命名要能让阅读者看出来这个变量的含义,在后续代码的查看中,不会搞不清是在传递什么信息。其他一些建议比如字符串变量,如果明确是’\0’结尾的,可以在变量后面加个’sz’后缀来表达这个含义(string_zero);如果是全局变量可以加个’g‘前缀;如果是常量,可以全大写声明等等。

函数命名则明确该函数具体是实现了什么功能,让调用者即便不看函数声明注释,也能基本明确函数的用途,不至于在看代码的过程中还需要调转到函数声明去看函数注释。其他建议比如是返回布尔类型的接口可以’is’开头等等。

代码文件命名合理也便于开发者组织代码目录,不至于一些接口实现存放到毫不相干的代码文件,或者找一个函数接口,不知道该去哪个源码文件查找。

四、代码风格

基本是控制好是否要换行,相近的代码紧挨在一起,没必要中间有换行,不同的处理逻辑代码则通过换行隔开,这样看起来也会比较清晰。变量声明也建议一行就一个变量声明,不建议一行里声明多个变量。

除了分行,就是要注意缩进,良好的缩进,可以清晰的明确各代码块,否则阅读上会有很大的障碍。 对于C语言,需要注意if语句,一定要有大括号,否则后面很容易因为新增语句而出错。

一行代码不宜过长,如果需要滚动编辑器的横条来看后面的代码,都建议进行换行来写。 像多条件判断的,一个条件一行书写也相对易读,需要注意换行的代码与上一级表达式的开头对齐。

单一函数实现代码也不要过长,明显感觉长了就可以考虑中间代码是否可以再封装一个单独接口调用。 对于源码文件也不能太长,上万行的代码都可以考虑看看是否可以将同一类的代码单独再放一个源码文件来进行维护。

五、可复用

如果一段代码需要拷贝过来直接使用,或者进行微小的修改,你都应该考虑下是否可以抽象出对应的方法后面直接复用。

六、测试代码

对于自己编写的接口,都建议自己花时间来写对应的测试代码进行测试,且要尽可能覆盖到所有代码,而不是等对接方写完代码再进行联调。对于自己写的测试代码可以单独存放到模块对应的test目录下,这样代码修改即可以做到及时自测,对于他人而言也可以通过你的测试代码来更快了解接口的使用。像开源代码基本会通过测试代码来便于了解使用。

七、明确接口职责无歧义

这一点本来应该放在命名规范里的,想了想还是单独拎出来说。

前面注释部分有讲到接口声明需要写详细,明确接口实现的功能,不过再单独明确一点,即使接口注释说明的和接口实际实现没什么问题,但与接口体现的命名也不该有冲突。比如一个get接口,别人一看就认为是获取值的,但如果你实现里却对这个值进行了修改操作,即使你接口声明里详细注释说明了,也是不对的。

保证接口命名规范和实际实现没有歧义。

八、代码组织

编写的新功能代码能以库的形式维护最好,便于后面方便裁剪支持、组件化等等。一个库的目录结构一般如下:
├── doc
├── README
├── src
└── test