MTK编程规范试行.docx

1、MTK编程规范试行MTK 编 程 规 范目 录目 录 2第1章 命名规则 41.1 共性规则 41.2 我公司的MTK开发命名规则 71.3 注释 8第2章 应用程序的目录结构 9第3章 Lib库规范 103.1 开放给客户使用的部分 103.2 不允许开放的部分 10第4章 文件结构 114.1 版本和版权的声明 113.2 头文件的结构 123.3 定义文件的结构 133.4 函数的说明 14第5章 程序的排版 15第6章 表达式和基本语句 186.1 运算符 186.2 复合表达式 196.3 条件语句 206.4 循环语句 21第6章 函数 216.1 函数的参数 226.2 函数的返

2、回值 226.3 函数编写的一般性规则 23第7章 内存管理 25第8章 可测性 25第9章 程序的效率 26第10章 审查及测试 28附录A ：C代码审查表 28附录B ：ASCII完整码表 32附录C：MTK重定义的数据类型 33第1章 命名规则比较著名的命名规则当推Microsoft公司的“匈牙利”法，该命名规则的主要思想是“在变量和函数名中加入前缀以增进人们对程序的理解”。例如所有的字符变量均以ch为前缀，若是指针变量则追加前缀p。如果一个变量由ppch开头，则表明它是指向字符指针的指针。“匈牙利”法最大的缺点是烦琐，例如int i, j, k; float x, y, z;倘若采用“

3、匈牙利”命名规则，则应当写成int iI, iJ, ik; / 前缀 i表示int类型float fX, fY, fZ; / 前缀 f表示float类型如此烦琐的程序会让绝大多数程序员无法忍受。没有一种命名规则可以让所有的程序员赞同，程序设计教科书一般都不指定命名规则。我们不要化太多精力试图发明世界上最好的命名规则，本章制定一种令大多数项目成员满意的命名规则，并在项目中贯彻实施。1.1 共性规则首先我们来看一下这样一组命名KHDL，KHXL，GDLB，CZLB，CXLB，GYLB，你能知道他的意思么？他们分别代表：客户大类，客户小类，股东类别，操作类别，查询类别，柜员类别。这是一个知名的软件公

4、司在几年前的一个证券柜台系统的命名。正因为这样他们招进新的程序员，不得不用大量的时间对他们进行培训，即使经过一个月的培训以后也没有人能全记住这些难懂的名词，不得不花大量的时间去查数据字典。这个公司最后花了大量的人力物力，用了将近一年时间改进这套命名系统。所以我们介绍的第一条规则就是：【规则1-1-1】标识符应当直观且可以拼读，可望文知意，不必进行“解码”。标识符采用英文单词或其组合，便于记忆和阅读。切忌使用汉语拼音来命名。如果单词不会写，请打开“金山词霸”，或者打开google中文翻译。程序中的英文单词一般不会太复杂，用词应当准确。例如不要为了省几个字符把CurrentValue写成NowVa

5、lue。【规则1-1-2】在MTK平台中编程，我们采用英文首字母大写的方式来分隔单词，用下划线来分隔前缀。命名的方式有多种，常用的有英文首字线大写方式，如AddUser；英文单词全部小写，用下划线划分单词，如add_user，这两种方式。MTK本身不同的程序也采用了这两种方式，这两种方式都是可以的。但是为了公司内部的统一，我们采用英文首字母大写的方式来强制统一（变量等第一个单词的首字母可以不大写）。【规则1-1-3】标识符的长度应当符合“min length & max information”原则。一般来说，长名字能更好地表达含义，所以函数名、变量名、类名长达十几个字符不足为怪。那么名字是否

6、越长约好？不见得! 例如变量名MaxVal就比MaxValueUntilOverflow好用。单字符的名字也是有用的，常见的如i,j,k,m,n,x,y,z等，它们通常可用作函数内的局部变量。【规则1-1-4】标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。新启用一个缩写，必须进行必要的注释说明。较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。示例：如下单词的缩写能够被大家基本认可。temp 可缩写为 tmp；flag 可缩写为 flg；statistic 可缩写为 stat；incre

7、ment 可缩写为 inc；message 可缩写为 msg；result 可缩写为 ret；value 可缩写为 val；【规则1-1-5】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。下面是一些在软件中常用的反义词组。add / remove; begin / end; create / destroy; insert / delete; first / last; get / release; increment / decrement; set / get; add / delete; lock / unlock; open / close; min / max; old

8、/ new; start / stop; next / previous; source / target; show / hide; send / receive; source / destination; cut / paste; up / down【规则1-1-6】除非是数字运算，程序中不允许出现数字标识符。在以往调程序调试过程中，我们要花费大量的时间去理解程序中数字的意义，因此以下写法是错误的。switch(OperationType) case 0: /ivr DoSomething(); break; case 1: /sms DoOtherthing(); break; cas

9、e 2: /wap . break; default: break;以上代码加入注释本身是没有什么错的，但现实中发现，如果另外的程序员接手这段代码，扩展这段代码，需要一定的时间。因为他在写其它程序的类似处理的时候，他的0代表sms，1代表IVR。程序中如果处理出现错误，同样我们也需要大量的时间来纠错。正确的写法如下：#define OPERATION_TYPE_IVR 0#define OPERATION_TYPE_SMS 1#define OPERATION_TYPE_WAP 2switch(OperationType) case OPERATION_TYPE_IVR: DoSomethin

10、g(); break; case OPERATION_TYPE_SMS: DoOtherthing(); break; case OPERATION_TYPE_WAP: . break; default: break;这样，就不用去理解0,1,2的意思了。MTK本身的代码这一部分还是做得挺好的。【规则1-1-7】为了防止某一软件库中的一些标识符和其它软件库中的冲突，可以为各种标识符加上能反映软件性质的前缀。比如说我们优化、改进、扩展了MTK的函数，我们就会加上公司名字的前缀。同样一些比较常用的函数，比如说字符编码的转换函数，为了避免跟其它第三方软件的函数冲突，我们也需要加上公司前缀。【规则1-

11、1-8】全局变量使用g_前缀，静态变量使用s_前缀。1.2 我公司的MTK开发命名规则【规则1-2-1】公司前缀只允许以下两种形式：Worthful_或者WT_。公司名缩写出再过WF，YSCF这样的名称，在此废除。【规则1-2-2】应用的目录名为首字母大写的目录名，头文件放在应用名+Inc的目录下，源文件放在应用名+Src的目录下。如应用百事通，取名KnowAll，头文件放在KnowAllInc下面，源文件放在KnowAllSrc下面。【规则1-2-3】应用宏开关用双下划线开始，双下划线结束。如：_KNOW_ALL_；【规则1-2-4】防重复引用，放在文件头的宏，使用双下划线开始，如果头文件以

12、“_H”结束,如果是源文件使用”_C”结束。如：#ifndef _KNOW_ALL_H, #ifndef _KNOW_ALL_C【规则1-2-5】应用内的常量，宏全用大写的字母，用下划线分割单词。如const int WT_SMS_SEND_NUMBER 3WT_SMS_NUMBER, WT_SMS_CM_INFO, WT_SMS_CU_INFO；【规则1-2-6】定义枚举用ENUM_当前缀的大写字母，用下划线分割单词。枚举名用_ENUM为后缀，如：typedef enum ENUM_EBR_FONT_SIZE_SMALL = 0, ENUM_EBR_FONT_SIZE_MEDIUM, ENU

13、M_EBR_FONT_SIZE_LARGE EBR_FONT_SIZE_ENUM;【规则1-2-7】定义结构名用_STRU或_STRUCT为后缀，如：typedef struct S8 file_name(FMGR_MAX_FILE_LEN + 1) *ENCODING_LENGTH; S8 file_ext(FMGR_MAX_EXT_LEN + 1) *ENCODING_LENGTH; FMGR_FILTER file_type; U32 file_size; U16 index; MYTIME time; U8 attribute; BOOL is_used; BOOL is_short;

14、 BOOL is_able_display; FMGR_FILE_INFO_STRU;【规则1-2-8】定义变量，不要同时使用U8，unsigned char两套定义。MTK本身定义了一套变量类型，我们要么使用MTK的，要么使用C本身的变量类型，不要两套混用。【规则1-2-9】变量和参数用小写字母开头的单词组合而成。变量和参数的名字应当使用“名词”或者“形容词名词”。如tmpValue, oldValue, currValue；【规则1-2-10】函数名用大写字母开头的单词组合而成，应当使用“动词”或者“动词名词”（动宾词组）。如GetField, SetField, InitData。1.3

15、 注释不要把程序和注释看作两个部分，注释是程序的一部分。一般注释能达到程序量的20%或以上。【规则1-3-1】通过对函数、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的，合理减少注释量。AddUser(); /* 添加用户 */以上注释显得多余。注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。【规则1-3-2】全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。示例：/* The ErrorCode when SCCP translate Global Title failure, as follows */ / 变量作用、含义/* 0 SUCCESS 1 GT Table error 2 GT error Others no use */ / 变量取值范围/* only function SCCPTranslate() in this