您可以捐助,支持我们的公益事业。

1元 10元 50元





认证码:  验证码,看不清楚?请点击刷新验证码 必填



  求知 文章 文库 Lib 视频 iPerson 课程 认证 咨询 工具 讲座 Model Center   Code  
会员   
   
 
     
   
 
 订阅
C语言 | 嵌入式C语言编程规范
 
作者 :嵌入式大杂烩
  1396  次浏览      16 次
 2023-6-5
 
编辑推荐:
在本文主要介绍了嵌入式C语言编程规范相关知识。希望对你的学习有帮助。
本文来自于CSDN ,由火龙果软件Linda编辑、推荐。

一、前言

刚开始学STM32的时候,看到一些比较规范的代码中的一些变量命名为ucValue 、g_ucPara等形式,当时觉得好不习惯,为什么要加uc、g_uc等,感觉好难看,后来才知道,这些前缀都有其约定俗成的意思,可以方便的知道变量的数据类型。

如:uc代表的是unsigned char,所以一个变量命名为ucValue就可以清楚的表明其为unsigned char的变量 。同样的,g代表global,即全局的,g_ucPara表明其为unsigned char类型的全局变量。

现在我们来看网上的一些比较权威的编码规范,比如安富莱的编码规范:

二、编程规范

1、文件与目录

(1)文件的命名

文件的命名要准确清晰地表达其内容,同时文件名应该精练,防止文件名过长而造成使用不便。在文件名中可以适当地使用缩写。 以下提供两种命名方式以供参考:

各程序模块的文件命名开头 2 个消协字母代表本模块的功能:

如:主控程序为 mpMain.c,mpDisp.c 等。

不写模块功能标识:

如:主控程序为 Main.c,Disp.c 等。

(2)头文件中段落安排顺序

// 1、文件头注释
// 2、防止重复引用头文件的设置
// 3、#include 部分
// 4、enum 常量声明
// 5、类型声明和定义,包括 struct、union、typedef 等
// 6、全局变量声明
// 7、文件级变量声明
// 8、全局或文件级函数声明
// 9、函数实现。按函数声明的顺序排列
// 10、文件尾注释

 

(3)在引用头文件时,不要使用绝对路径

如果使用绝对路径,当需要移动目录时,必须修改所有相关代码,繁琐且不安全;使用相对路径,当需要移动目录时,只需修改编译器的某个选项即可。例如:

#include “/project/inc/hello.h” /* 不应使用绝对路径 */
#include “../inc/hello.h”       /* 可以使用相对路径 */

 

(4)在引用头文件时 ,使用<>还是""

#include <stdio.h>      /* 标准头文件 */
#include <projdefs.h>   /* 工程指定目录头文件 */
#include “global.h”     /* 当前目录头文件 */
#include “inc/config.h” /* 路径相对于当前目录的头文件 */

 

(5)防止头文件被重复引用

#ifndef __DISP_H /* 文件名前名加两个下划线“__”,后面加 “_H”
#define __DISP_H
...
...
#endif

 

(6)头文件中只存放“声明”而不存放“定义”

(7)文件的长度

文件的长度没有非常严格的要求,但应尽量避免文件过长。一般来说,文件长度应尽量保持在 1000 行之内 。

2、排版

(1)程序块要采用缩进风格编写,缩进的空格数为 4 个。

(2)相对独立的程序块之间、变量说明之后必须加空行 。

(3) 较长的语句或函数过程参数(>80 字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。

(4) 不允许把多个短语句写在一行中,即一行只写一条语句

(5)程序块的分界符(如大括号‘{’和‘}’ )应各独占一行并且位于同一列

(6) 在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。

示例:

逗号、分号只在后面加空格。

比较操作符,赋值操作符"="、 “+=”,算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格。

"!"、"~"、"++"、"–"、"&"(地址运算符)等单目操作符前后不加空格。

"->"、"."前后不加空格。

if、for、while、switch 等与后面的括号间应加空格,使 if 等关键字更为突出、明显,函数名与其后的括号之间不加空格,以与保留字区别开

3、注释

(1) 一般情况下,源程序有效注释量必须在 20%以上。

说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁 。

(2) 在文件的开始部分,应该给出关于文件版权、内容简介、修改历史等项目的说明。

在创建代码和每次更新代码时,都必须在文件的历史记录中标注版本号、日期、作者、更改说明等项目。 下面是一个范例,当然,并不局限于此格式,但上述信息建议要包含在内。

(3)对于函数,在函数实现之前,应该给出和函数的实现相关的足够而精练的注释信息。

示例:

下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。

(4) 边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。

(5) 注释的内容要清楚、明了,含义准确,防止注释二义性。

说明:错误的注释不但无益反而有害。注释主要阐述代码做了什么(What),或者如果有必要的话,阐述

为什么要这么做(Why),注释并不是用来阐述它究竟是如何实现算法(How)的。

(6) 避免在注释中使用缩写,特别是非常用缩写。

说明:在使用缩写时或之前,应对缩写进行必要的说明。

(7) 注释应与其描述的代码靠近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,

不可放在下面,如放于上方则需与其上面的代码用空行隔开。

示例:如下例子不符合规范。

例 1:不规范的写法

例 2:不规范的写法例

3:规范的写法例

4:不规范的写法,显得代码过于紧凑

例 5:规范的写法

(8) 注释与所描述内容进行同样的缩排。

说明:可使程序排版整齐,并方便注释的阅读与理解。

例 1:如下例子,排版不整齐,阅读稍感不方便。

例 2:正确的布局。

(9) 对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。

说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。

(10) 对于 switch 语句下的 case 语句,如果因为特殊情况需要处理完一个 case 后进入下一个 case 处理,必须在该 case 语句处理完、下一个 case 语句前加上明确的注释。

说明:这样比较清楚程序编写者的意图,有效防止无故遗漏 break 语句。

示例(注意斜体加粗部分):

(11) 注释格式尽量统一,建议使用“/ …… /”,因为 C++注释“//”并不被所有 C 编译器支持。

(12) 注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能非常流利准确的用英文表达。

说明:注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文。

(13) 标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避

免使人产生误解。

说明:较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。

示例:如下单词的缩写能够被大家基本认可。

temp 可缩写为 tmp;
flag 可缩写为 flg;
statistic 可缩写为 stat;
increment 可缩写为 inc;
message 可缩写为 msg; 

 

(14) 命名中若使用特殊约定或缩写,则要有注释说明。

说明:应该在源文件的开始之处,对文件中所使用的缩写或约定,特别是特殊的缩写,进行必要的注释说明。

(15) 自己特有的命名风格,要自始至终保持一致,不可来回变化。

说明:个人的命名风格,在符合所在项目组或产品组的命名规则的前提下,才可使用。(即命名规则中没有规定到的地方才可有个人命名风格)

(16) 对于变量命名,禁止取单个字符(如 i、j、k…)

建议除了要有具体含义外,还能表明其变量类型、数据类型等,但 i、j、k 作局部循环变量是允许的。变量,尤其是局部变量,如果用单个字符表示,很容易敲错(如i写成j),而编译时又检查不出来,有可能为了这个小小的错误而花费大量的查错时间 。

(17) 命名规范必须与所使用的系统风格保持一致,并在同一项目中统一

比如采用 UNIX 的全小写加下划线的风格或大小写混排的方式,不要使用大小写与下划线混排的方式,用作特殊标识如标识成员变量或全局变量的 m_和 g_,其后加上大小写混排的方式是允许的。

示例: Add_User不允许,add_user、AddUser、m_AddUser允许。

(18) 除非必要,不要用数字或较奇怪的字符来定义标识符。

示例:如下命名,使人产生疑惑。

应改为有意义的单词命名:

4、可读性

(1) 注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。

(2) 避免使用不易理解的数字,用有意义的标识来替代。

示例:如下的程序可读性差

应改为如下形式 :

(3) 不要使用难懂的技巧性很高的语句,除非很有必要时。

说明:高技巧语句不等于高效率的程序,实际上程序的效率关键在于算法。

示例:如下表达式,考虑不周就可能出问题,也较难理解。

应分别改为如下:

5、变量、 结构、 常量、 宏

(1) 为了方便书写及记忆,变量类型采用如下重定义:

(2) 常见类型的前缀

对于一些常见类型的变量,应在其名字前标注表示其类型的前缀。前缀用小写字母表示。前缀的使用请参照下列表格中说明。

(3) 变量作用域的前缀

为了清晰的标识变量的作用域,减少发生命名冲突,应该在变量类型前缀之前再加上表示变量作用域的前缀,并在变量类型前缀和变量作用域前缀之间用下划线 - 隔开。

具体的规则如下:

对于全局变量(global variable),在其名称前加g和变量类型符号前缀。

uint32_t g_ulParaWord;
uint8_t g_ucByte;

 

对于静态变量(static variable),在其名称前加s和变量类型符号前缀。

static uint32_t s_ulParaWord;
static uint8_t s_ucByte;

 

函数内部等局部变量前不加作用域前缀。

对于常量,当可能发生作用域和名字冲突问题时,以上几条规则对于常量同样适用。注意,虽然常量名的核心部分全部大写,但此时常量的前缀仍然用小写字母,以保持前缀的一致性。

(4) 结构体命名规则

表示类型的名字,所有名字以小写字母tag开头,之后每个英文单词的第一个字母大写(包括第一个单词的第一个字母),其他字母小写,结尾_T 标识。单词之间不使用下划线分隔,结构体变量以 t 开头。 如:

/* 结构体命名类型名 */
typedef struct tagBillQuery_T
{
...
}BillQuery_T;
/* 结构体变量定义 */
BillQuery_T tBillQuery;

 

(5)对于枚举定义全部采用大写,结尾_E 标识。

(6)常量、宏、模版的名字应该全部大写。如果这些名字由多个单词组成,则单词之间用下划线分隔。

#define LOG_BUF_SIZE 8000

6、函数

(1) 函数的命名规则。

每一个函数名前缀需包含模块名,模块名为小写,与函数名区别开。

如:uartReceive(串口接收)

备注:对于非常简单的程序,可以不加模块名。

(2)函数的形参。

函数的的形参都以下划线_开头,已示与普通变量进行区分,对于没有形参为空的函数(void)括号紧跟函数后面。

uint32_t uartConvUartBaud(uint32_t _ulBaud)

{

(3) 一个函数仅完成一件功能。

(4) 函数名应准确描述函数的功能,使用动宾词组为执行某操作的函数命名。

说明:避免用含义不清的动词如process、handle等为函数命名,因为这些动词并没有说明要具体做什么。

示例:参照如下方式命名函数。(5)避免设计五个以上参数函数,不使用的参数从接口中去掉。

说明:目的减少函数间接口的复杂度,复杂的参数可以使用结构传递。

(6)在调用函数填写参数时,应尽量减少没有必要的默认数据类型转换或强制数据类型转换。

说明:因为数据类型转换或多或少存在危险。

(7) 防止把没有关联的语句放到一个函数中。

示例:如下函数就是一种随机内聚。矩形的长、宽与点的坐标基本没有任何关系,故以上函数是随机内聚。

应如下分为两个函数:

 

   
1396 次浏览       16
相关文章

深度解析:清理烂代码
如何编写出拥抱变化的代码
重构-使代码更简洁优美
团队项目开发"编码规范"系列文章
相关文档

重构-改善既有代码的设计
软件重构v2
代码整洁之道
高质量编程规范
相关课程

基于HTML5客户端、Web端的应用开发
HTML 5+CSS 开发
嵌入式C高质量编程
C++高级编程


最新活动计划
信息架构建模(基于UML+EA)3-21[北京]
软件架构设计师 3-21[北京]
图数据库与知识图谱 3-25[北京]
业务架构设计 4-11[北京]
SysML和EA系统设计与建模 4-22[北京]
DoDAF规范、模型与实例 5-23[北京]
 
 
最新文章
代码整洁 vs 代码肮脏
代码审计--源代码审计思路
代码审计思路
代码重构之道
clean code代码整洁
最新课程
设计模式原理与应用
从需求过渡到设计
软件设计原理与实践
如何编写高质量代码
单元测试、重构及持续集成
更多...   
成功案例
某企业 基于IPD的嵌入式软件开发
某企业 自我认知、情绪管理和沟通
某企业 思维导图方法与实践
中盛益华 卓越管理者必须具备的五项能
世纪高通 创新创造突破性产品——体系
更多...