C语言软件规范

请下载   SVN + Doxygen 使用大全

软件规范

 

@todo.  根据函数库的关系，建立起调用拓扑图，进而是封装分析

 

命名:

原则：尽量短小，适用名词、动词的缩写格式. 这样代码看起来紧凑，精悍；

结构体用后缀Type结尾, 其定义的实际变量用t开头。

枚举用List结尾（consume_StateList）,实际变量以e开头

指针以p开头

宏若不是大写,用macro结尾

 

名称组成

每个驱动（函数、全局变量）都有单独的前缀(大写)，比如DAC_InitType、DAC_StructInit（）。

局部变量尽量小写，用下划线分开各部。

后面的名词写在一起，中间没有_ ，每个单词开头大写，后面的小写。

这样以来，可以不用翻看前面的名称定义，直接用VC编辑工具就能记得，这样提高了代码速度

Eg.   状态机的状态以state开头，便于查找，前面再加上文件的前缀

 

缩写示例:

Control:  Ctrl

Read:rd

Write:wr

Prepare:pre

Destination  dst

Source    src

Compare   cmp

System    sys

Return:ret

Buffer:buf

Parameter:param

Address:add

Increase: inc

Decrease: dec

Record:rec

Public:pub

C语言关键词里面，enum,const属于安全检查的，一种用法的cons除外，其不对应物理实际

 

 

类型的约定

ret： INT

state: 视情况 INT or UINT

len:   UINT

buffer: BYTE

money: UINT

i: INT  (  用于通常的for循环 )

 

 

代码结构

●原则：尽量封装在一块，少用分散、临时的全局变量

注意模块的封装性，尽量减小模块间的耦合性；宏的定义尽量集合在一块，采用enum封装（增添宏很方便，不用担心与同类宏的冲突，按键的键值也可以这样定义）；变量采用结构体封装，这样看起来整体划一; LocalVariable用于一个.c与.h组成的整体中，用来把其临时变量集中在一块

 

●一个.c与相应（通常前面的名字一样）的.h作为一个整体。

输出：少用输出去的变量，如若必须，要把它改成函数获取的方式；函数直接声明（可不加extern,因为函数有声明的方式）即可。

输入：需要其它模块配合实现的输入项这样实现。函数加上extern关键词。

（默认的调用项可以不写）

 

●If else尽量配套,这样看起来,结构整齐、一目了然

 

●每个.h使用防冲突宏声明。画好系统的调用图，可以把.h统一放入一个配置文件内，如STM32的官方驱动

●健壮性：

原则：软件很大程度上是技能，包括熟练。  如果是不写代码，先写出这些，意义是不大的。在于养成的习惯，和写程序的感觉

 

1.确实要把每个情况、每个判断语句的出口都考虑到，这样函数就健壮了；每个可能的情况考虑到，暂时实现不了的，写上提醒--//@ to do:;

 

2.Memcpy等的地方注意溢出检查

 

封装的方法和架构

减少耦合性,把一个功能拆分成各个函数时注意：<1>各个函数功能的自然性、美观;<2>怎样这些函数组合起来能整合出更多的功能,即整体大于个体，同时应用程序写起来美观，不别扭 <3>每个函数应该放在哪个文件内(其出口应写在.h里),每个文件功能尽量独立，程序不迁就。

 

规划架构时，注意从状态机、对象化入手，先有愿景，然后从宏观到微观，用人性化的方法以及类人性的行为规划各个文件（.c .h）与各个函数的功能、出口、控制。  一个文件是一个模块，其封装应类似于linux对驱动的封装，比如注册(register)  读（read） 写(write)  控制(ctrl)  删除(del) 等。所以看高级语言及操作系统对底层软件是有指导意义的

 

 

编译器的使用

仔细阅读编译器的官方说明。 C语言或者编出来的汇编语言是把平面性的FLASH内存数据立体起来的一个结构，或者说后者是前者从三维空间到二维空间的一个映射。  这些编译器的就是很好分析这些映射的工具。比如IAR的英文说明书，有很多细节，可以大大方面这些分析

注释结构

 

一般，首行起始的注释是对下一行的功能注解；紧贴在要注释内容后面而不另起一行的注释是对函数内部参数的说明

 

这些可以用VC的插件Visual Assist X options实现

I..c整体的注释

/**

* @file

* @brief 

* @lib base

* @version

* @author xhh

* @date

* @note

*      1.

*      2.

*

* @copy

*

* 此代码为XXXXXX公司项目代码，任何人及公司未经许可不得复制传播，或用于

* 本公司以外的项目。本司保留一切追究权利。

*

* <h1><center>&copy; COPYRIGHT 2011 xuehui869</center></h1>

*/

 

/* Includes------------------------------------------------------------------*/

 

/* Public-------------------------------------------------------------*/

 

/* Private typedef-----------------------------------------------------------*/

/* Private define------------------------------------------------------------*/

/* Private macro-------------------------------------------------------------*/

/* Private variables ---------------------------------------------------------*/

/* Private function prototypes-----------------------------------------------*/

/* Private functions---------------------------------------------------------*/

 

//文件正文

 

 

/******************* (C) COPYRIGHT 2011 XUEHUI869 *****END OFFILE****/

 

 

 

II.文件段的注释

 /*********************************************

*----------------------------------------------

************************************************/

用于分割一个.c里面的各个功能性代码段

 

III．函数头的注释

/**

* @brief

* @param[in]

* @param[out]

* @return

* @note

*/

函数头

 

IV．其它

//@ to do:

待做事项

//@to note:

需注意的地方