=== 一般代码规范,General Regulations for Coding (quanben,2007-3-21试行) ===
== 历史 ==
2007-04-28-09:04,修订,放宽了对数字命名的限制。
2007-04-18-09:38,增订了一些建议。
2007-04-04-11:07,“注释”板块增订。
2007-03-30-14:42,微小修改。
2007-03-28-22:12,修订。
2007-03-21-23:12,初订。
== 目的 ==
规定C/C++的关键字的编码。
== 基本原则 ==
1. 可分辨,无歧义或无显著的歧义;
2. 为工程实践提供快速命名指导,且有助于快速输入;
3. 美观。
== 词法评价的几个等级 ==
1. 合法
与本规范相容的情形
1.1 推荐的或可行的
本规范明确推荐的方法或默许的方法
1.2 不推荐的
本规范明确表示不推荐的方法
2. 非法
与本规范不相容的情形
== 概念定义 ==
1. 词元 能表达全部或部分确切含义的不含空格的字符串。
2. 正规化 将词元转换成目标关键字中的对应子串的过程。后文不加说明,“词元”一般指正规化后的原始词元。
3. 分解 或叫解析。将目标关键字解释为词元的连接的过程。
4. 下划线连接 在目标串中相邻词元用下划线连接;“双侧下划线连接”指某词元的两侧如有词元则与之用下划线连接。
== 命名流程 ==
1. 根据语意构造词元序列,左侧建议采用较大或较重要的概念的词;
2. 将每个词元正规化;
3. 从左至右扫描,根据具体连接方案连接各正规概念串为目标串。
== 词元和连接原则 ==
= 强制规则 =
根据C/C++语法规范,关键词首部不得为数字,因此数字起始的词元不得作为最左词元;
全小写的词元必须双侧下划线连接;
相互直接连接的词元的后一个必须是首字母大写;
词元除首字母外其余字母必须为小写;
词元最少可以是一个;
下划线可用于支持词元序列根据含义的划分。
= 建议规则 =
包含数字的词元建议采用双侧下划线连接;
对于大写过多的情形,可以寻求词元重组支援,见例2。
= 举例 =
例1. 类型定义,MyVertex2iStack,分解为My,Vertex2i(2D的整数顶点),Stack。
例2. 类型定义,MySInt32,分解为My,S(有符号型),Int32,可以将S和Int32合并为一个词元,表示为Sint32,于是可写为MySint32。
= 具体命名方案 ==
= 变量 =
变量以扩展的骆驼法作为连接方案。变量不允许大写字母起始。
变量的保留词元包括:
1. 域说明前缀
k 常量(规定)
g 全局,静态的类成员(规定)
m 非静态的类成员变量(规定)
v 一般的其他变量,不常用(建议)
2. 常用的类型说明前缀(建议)
2.1 强烈建议采用的
p 指针
pp 指向指针的指针
psz 以0结尾的字符串指针(sz则用于字符串数组缓冲)
2.2 非常建议采用的
n 整数类型
i 表示序号索引
num 表示个数,也可用num of双词元作为前缀;语意和词元count相近。
id 表示标识
str 字符串类型(C++)
2.3 一般建议采用的
arr 数组,FDC建议使用_arr后缀指明数组。
上述保留词元必须正规化为小写。
尽量用一些具有贴切含义的表达,如:
int studentAgeList[10]; // [:List:]后缀暗示数组,不被FDC建议。
Box boxes[20]; // 复数暗示数组
序号一般用i,j,k等。
举例:
例1,全局的学生姓名(0结尾)字符串数组。词元序列:g,psz,student,names。连接为:p_pszStudentNames。
例2,全局的x方向Y分量宏块的个数。词元序列:g,mb(macroblock的缩写), cnt(count的缩写), y, x。连接为:g_MbCntY_x。
例3,ODBC数据接口。词元序列:ODBC,data,interface。连接为:odbcDataInterface。
全小写法是上述规则的一个特例。
某些场合的可不使用上述命名规范,如常用模板类参照STL规范定义内部变量。
= 函数 =
函数规则基本和变量一致,只是目标串必须是首字母大写,并且建议以操作对象的类型作为词元序列的首部(概念树的根部)。
举例:
学生课程增加函数。词元序列:student,add,course。连接为:Student_AddCourse。(其中Student作为操作对象成为一个相对独立词元)
例外:对于一些基元应用,函数允许采用全小写,如底层开发,内联函数,某些早期意义的C语言开发,常用模版类(参照STL规范)等。
= 类型 =
类型规则基本和变量一致,目标串也必须首字母大写。
举例:
AVL树。词元序列:AVL,tree,连接为:AvlTree
类型定义的一般格式,以结构为例:
typedef struct _AvlTree
{
// members
} AvlTree;
例外:对于一些基元应用,类型允许采用全小写,但自定义类型建议用_t结尾。如底层开发,某些早期意义的C语言开发,常用模版类(参照STL规范)等。
= 宏定义 =
宏定义全大写,下划线分割。对于仅作为定义检查的宏定义,采用下划线起始,其余的宏定义不使用下划线起始。
宏开关(不强烈)建议以_SWITCH结尾。
例外:允许某些宏函数参照函数命名规则(很不建议),如:
Endian_U32_BToN 用于将32位无符号大端整数转换为本地整数。(作为参考,Apple的定义为:EndianU32_BtoN)
= 打印信息 =
起始符号:
':' 输出
'>' 输入
'!' 错误信息
'%' 调试信息
= 注释 =
[::] 关注符号,表示其中内容为对代码内容的引用。也可用`'符号,但不推荐。
.. 注释内容层次(每层2个句点)
<> XML式注释,一般可用于过程级描述。
== 注释分段,一般用于文件级描述。
NTT Not Thoroughly Tested缩写。
TODO 工作需求。如:/* TODO: Initialization code here. */