如何让你的程序赏析悦目-帕斯卡命名法

帕斯卡命名法

属性

前缀	含义
g_	全局变量
c_	常量
m_	c++类成员变量
s_	静态变量

类型

前缀	含义
a	数组
p	指针
fn	函数
v	无效
l	句柄
h	长整型
b	布尔
f	浮点型 、文件
dw	双字
sz	字符串
n	短整型
d	双精度浮点
cnt	计数
c \ ch	字符
n \ i	整型
by	字节
w	字
r	实型
u	无符号

描述

前缀	含义
Max	最大
Min	最小
Init	初始化
Temp \ T	临时变量
Src	源对象
Dest	目标

帕斯卡命名法

• 帕斯卡命名法指当变量名和函式名称是由二个或二个以上单词连结在一起，每个单词首字母大写。
• 单字之间不以空格断开或连接号（-）、底线（_）连结，第一个单词首字母采用大写字母；后续单词的首字母亦用大写字母，例如：FirstName、LastName。 也有人称之为大驼峰式命名法（Upper Camel Case） 。

下划线命名法

• 下划线命名法变量名和函式名称是由二个或二个以上单词连结在一起，每个单词用下划线隔开并且单词都是小写。
• 例如：print_employee。下划线命名法是随着C语言的出现流行起来的，在UNIX/LIUNX这样的环境，以及GNU代码中使用非常普遍。

文件与目录

文件的命名

• 文件的命名要准确清晰地表达其内容，同时文件名应该精练，防止文件名过长而造成使用不便。在文件名中可以适当地使用缩写。以下提供两种命名方式以供参考：
• 各程序模块的文件命名开头 2 个消协字母代表本模块的功能：

如：主控程序为 mpMain.c，mpDisp.c 等。

• 不写模块功能标识：

如：主控程序为 Main.c，Disp.c 等。

头文件中段落安排顺序

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

在引用头文件时，不要使用绝对路径

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

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

在引用头文件时 ，使用<>还是""

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

防止头文件被重复引用

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

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

/* 模块1头文件：module1.h */
extern int a = 5; 
/* 在模块1的 .h 文件中声明变量 */ 

文件的长度

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

排版

• 程序块要采用缩进风格编写，缩进的空格数为 4 个。
• 相对独立的程序块之间、变量说明之后必须加空行 。

void DemoFunc(void){
		uint8_t i;
		/* 功能块1 */
		for(i = 0; i < 10; i++){
				
		}
		//不同的功能块间空一行
		/* 功能块2 */
		for(i = 0; i < 10; i++){
				
		}
}

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

if((ucParam1 == 0) && (ucParam2 == 0) && (uParam3 == 0))
		|| (ucParam4 == 0){
		//长表达式需要换行书写
}

• 不允许把多个短语句写在一行中，即一行只写一条语句

rect.length = 0; rect.width = 0;//错误写法

rect.length = 0;
rect.width = 0;//正确写法

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

~~for(){
		
}//不规范

for()
{

}//规范~~

• 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如－>），后不应加空格。

示例：

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

int_32 a, b, c;

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

if(current_time >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;

• “!”、"~"、"++"、"–"、"&"（地址运算符）等单目操作符前后不加空格。

*p = 'a';
flag = !sEmpty;
p = &mem;
i++;

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

p->id = pid;

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

if (a>=b && c >d){

}

注释

一般的，源程序有效注释量必须在 20％以上。

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

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

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

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

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

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

• 错误的注释不但无益反而有害。注释主要阐述代码做了什么（What），或者如果有必要的话，阐述为什么要这么做（Why），注释并不是用来阐述它究竟是如何实现算法（How）的。

避免在注释中使用缩写，特别是非常用缩写。

• 说明：在使用缩写时或之前，应对缩写进行必要的说明。

注释应与其描述的代码靠近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置， 不可放在下面，如放于上方则需与其上面的代码用空行隔开。

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

• 例 1：不规范的写法

/* 测试 */
															//规范写法无此空行
test_id = test[index].index;
test_val = test[index].value;

• 例 2：不规范的写法

test_id = test[index].index;
test_val = test[index].value;
/* 测试 */ //规范写法注释应在语句前

• 例 3：规范的写法

/* 测试 */
test_id = test[index].index;
test_val = test[index].value;

• 例 4：不规范的写法，显得代码过于紧凑

/* code one comments */
program code one
/* code two comments */
program code two

• 例 5：规范的写法

/* code one comments */
program code one

/* code two comments */
program code two

注释与所描述内容进行同样的缩排

• 可使程序排版整齐，并方便注释的阅读与理解。
• 例 1：如下例子，排版不整齐，阅读稍感不方便。

void example_fun( void )
{
		/* code one comments */
		CodeBlock One
				
				/* code two comments */
				CodeBlock Two
}

• 例 2：正确的布局。

void example_fun(void){
		/* code one comments */
		CodeBlock One

		/* code two comments */
		CodeBlock Two
}

对变量的定义和分支语句（条件分支、循环语句等）必须编写注释

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

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

• 这样比较清楚程序编写者的意图，有效防止无故遗漏 break 语句。
• 示例（注意斜体加粗部分）：

case CMD_FWD:
		ProcessFwd():
	
		if(){

		}

		if(){
				***ProcessCFW_B(); /* now junp into case CMD_A */***
		}

case CMD_A:
		ProcessA();
		break

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

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

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

标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避 免使人产生误解

• 较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。
• 示例：如下单词的缩写能够被大家基本认可。

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

命名中若使用特殊约定或缩写，则要有注释说明

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

自己特有的命名风格，要自始至终保持一致，不可来回变化

• 个人的命名风格，在符合所在项目组或产品组的命名规则的前提下，才可使用。（即命名规则中没有规定到的地方才可有个人命名风格）

对于变量命名，禁止取单个字符（如 i、j、k…）

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

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

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

除非必要，不要用数字或较奇怪的字符来定义标识符

• 示例：如下命名，使人产生疑惑。

uint8_t dat01;
void Set00(uint8_t c);

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

uint8_t ucWidth;
void SetParam(uint8_t _ucValue);

可读性

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

• 正确写法

word = (high << 8) | low;
if ((a | b) && (a &c))
if ((a | b) < (c &d))

• 错误写法

word = high << 8 | low
if (a | b && a & c)
if (a | b < c & d)

避免使用不易理解的数字，用有意义的标识来替代

• 示例：如下的程序可读性差

if (Trunk[index].trunk_state == 0) {
	Trunk[index].trunk_state = 1;
}

应改为如下形式 ：

if (Trunk[index].trunk_state == 0) {
	Trunk[index].trunk_state = TRUNK_BUSY;
}

不要使用难懂的技巧性很高的语句，除非很有必要时

• 高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。
• 如下表达式，考虑不周就可能出问题，也较难理解。

* stat_poi ++ +=1
* ++ stat_poi += 1;

应分别改为如下：

*stat_poi +=1;
stat_poi++; /* 相当于 "stat_poi ++ +=1"*/

++stat_poi;
*stat_poi += 1; /* 相当于 "++ stat_poi += 1;"*/

变量、 结构、 常量、 宏

为了方便书写及记忆，变量类型采用如下重定义

typedef unsigned char uint8_t
typedef unsigned short uint16_t
typedef unsigned long int uint32_t

typedef signed char int8_t
typedef signed short int16_t
typedef signed long int int32_t

常见类型的前缀

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

变量作用域的前缀

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

对于全局变量（global variable），在其名称前加g和变量类型符号前缀。

uint32_t g_ulParaWord;
uint8_t g_ucByte;

对于静态变量（static variable），在其名称前加s和变量类型符号前缀。

static uint32_t s_ulParaWord;
static uint8_t s_ucByte;

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

结构体命名规则

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

typedef enum{
		KB_F1 = 0; /* F1键代码 */
		KB_F2,
		KB_F3
}KEY_CODE_E;

对于枚举定义全部采用大写，结尾_E 标识。

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

#define LOG_BUF_SIZE 8000

函数

函数的命名规则。

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

uartReceive(串口接收)

• 备注：对于非常简单的程序，可以不加模块名。

函数的形参。

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

uint32_t uartConvUartBaud(uint32_t _ulBaud){

}

一个函数仅完成一件功能。

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

• 避免用含义不清的动词如process、handle等为函数命名，因为这些动词并没有说明要具体做什么。
• 参照如下方式命名函数。

void PrintRecord(uint32_t _RecInd);
int32 InputRecord(void);
uint8_t GetCurrentColor(void);

避免设计五个以上参数函数，不使用的参数从接口中去掉。

• 目的减少函数间接口的复杂度，复杂的参数可以使用结构传递。

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

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

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

• 如下函数就是一种随机内聚。

void InitVar(void){
		Rect.length = 0;
		Rect.Width = 0; /* 初始化矩形的长宽 */

		Point.x = 10;
		Point.y = 10; /* 初始化点的坐标 */ 
}

• 矩形的长、宽与点的坐标基本没有任何关系，故以上函数是随机内聚。应如下分为两个函数：

void InitRect(void){
		Rect.length = 0;
		Rect.Width = 0; /* 初始化矩形的长宽 */
}

void InitPoint(void){
		Point.x = 10;
		Point.y = 10; /* 初始化点的坐标 */ 
}

• 文章内容总结于网络与书籍，可能与其他博客大同小异，见谅。