一、文档简介
一份编写规范的代码会让人赏心悦目,养成良好的代码编写习惯是每一个程序员应该具备的基本素养!
当项目需要多人合作共同编写的时候,共同的风格、方式就变得尤为重要,代码配合的效率也会提高,因此编写本来规范代码编写的风格,请各位工程师参照。当然如果有不同的见解或需要增加的内容,请直接沟通。
二、整体风格编排
针对总的书写格式,包括对齐、缩进、空格、括号等等标准,需要使用Astyle软件辅助配置,配置方式参照如下
AStyle all files:!E $E*.c $E*.h --style=allman --indent=spaces=4 --indent-preproc-block --pad-oper --pad-header --unpad-paren --suffix=none --align-pointer=name --lineend=linux --convert-tabs --delete-empty-lines --break-blocks -p -U --break-elseifs --verbose
AStyle current file :-n !E --style=allman --indent=spaces=4 --indent-preproc-block --pad-oper --pad-header --unpad-paren --suffix=none --align-pointer=name --lineend=linux --convert-tabs --delete-empty-lines --break-blocks -p -U --break-elseifs --verbose
三、细节描述
3.1标识符命名规则
1)标识符应当直观且简介,可望文知意,不必进行“解码”。
例如:标识符最好采用英文单词或其组合,便于记忆和阅读。切忌使用汉语拼音来命名。程序中的英文单词一般不会太复杂,用词应当准确。例如不要把Current_Value写成Now_Value。
2)标识符的长度应当符合“min-length&&max-information”原则,单词最长不超过5个。
3)命名规格尽量与所采用的开发工具的风格一致。
例如,程序中的标识符通常采用大小写混排的方式,加下划线,比如Add_Child。一个单词的可以小写,例如value。
4)程序中不要出现仅靠大小写区分的相似的标识符
5)变量的名字应当使用名词或形容词+名词
6)用正确的反义词组命名具有互斥意义的变量或相反动作的函数等
7)尽量避免使用名字中出现数字编号,如Value1,Value2等,除非逻辑上的确需要编号。
8)常量全用大写字母,用下划线分割单词
9)静态变量加前缀s_(表示static)
10)如果不得已需要使用全局变量,则使全局变量前加前缀g_(表示global,暂时不用)
11)宏定义全部要大写,单词之间用下划线分开
12)变量类型全部使用u8 、u16、s16等sys.h中的数据类型
13)函数的命名与变量相同
14)禁止无参数的函数命名时()内为空,应填写void
15)函数的传递参数不超过5个
3.2 长代码和判断语句书写规范
1)同一行代买最长不超过80个字符,否则换行编写
2)如果程序中需要使用数字进行逻辑判断,数字在前。例如if(5==Value)
3)判断中建议使用≥和≤替代>和<
4)判断条件最好不要使用数字,数字用宏定义或布尔量代替,除非能特别直观的知道数字的代表含义。同样,for()中的截止条件最好也不用数字
3.3全局变量的书写规范
1)在不必要的情况下避免使用全局变量
2)全局变量如果作用于只是在同一文件中的其他地方调用,就用static限定其作用域(非必要)。
3)全局变量如果作用是多个文件,定义写在xx.c文件中,声明写在对应的xx.h文件中,并且用extern关键字声明
3.4 主循环或中断中延时和嵌套的处理
1)主循环或中断中,非必要情况下避免使用delay()函数进行延时。主循环中的延时评估是否可以使用定时器的定时功能替代。
2)在多重循环逻辑中,应将最忙的循环放在最内层。例如
for (row = 0; row < 100; row++)
{
for (col = 0; col < 5; col++)
{
sum += a[row][col];
}
应该改为
for (col = 0; col < 5; col++)
{
for (row = 0; row < 100; row++)
{
sum += a[row][col];
}
3)避免循环体中包含判断语句,如果确实需要,考虑是否可以把判断语句放在循环体外
4)尽量使用乘法、位与其它方法替代除法
5)非特殊情况,不同类型的中断设置不同的抢占优先级
3.5函数的使用
1)函数的传递参数不超过5个
2)对于不需要数值回传的使用值传递的方式
3)函数优先使用返回值,而不是输出函数
4) 使用强类型参数,避免使用void*
四、.C和.H文件的说明
1)具有单独功能的.c文件都需要配备对应的.h文件,特殊情况除外
2).c文件建议不超过2000行
3).c文件中必须是同一类型功能的函数,实现不同功能的函数不能放在同一个c文件中。例如:ADC的采集和继电器的控制不应放在一起
4).c文件中禁止包含用不到的.h文件,如果发现及时删除
5)每一个功能都建立一个readme.txt的文件,对于调试进度、工程修改、待调试的问题和想法,都需要写明。
五、注释的风格
5.1文件头部注释
文件头绪应当注释出
作者:
版本:
文件功能描述:
修改记录:
日期:
特殊说明:
5.2函数头部注释
函数头部注释使用/**********************/模式,需要写明的参数有
函数名:
函数功能:
输入参数:
输出参数:
返回值:
5.3数据结构的注释
数据结构声明(包括结构、类、枚举),如果其命名不是充分注释的,必须加注释。低于数据结构的注释应放在其上方相邻的位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
/* sccp interface with sccp user primitive message name */
enum SCCP_USER_PRIMITIV
{
N_UNITDATA_IND, /* sccp notify sccp user unit data come */
N_NOTICE_IND, /* sccp notify user the No.7 network can not */
/* transmission this message */
N_UNITDATA_REQ, /* sccp user's unit data transmission request*/
};
5.4对变量的注释
变量在定义时要写明其功能,取值范围
5.5 注释的注意事项
1)注释的原则是有助于理解阅读,语言必须准确、易懂、简洁
2)边写代码边注释,修改代码的同事修改相应注释,以保证注释与代码的一致性。不再有用的注释要删除。
3)注释的内容要清楚、明了,含义准确,防止注释二义性,错误的注释不烦无益反而有害
4)对代码的注释应该在其上方或右方相邻位置,不可放在下面,如放在上方需与其上面的代码用空行隔开