OfficeCodeStyle第5章.docVIP

5.格式规范 下一章描述了不同格式之间的转换,即使用通用代码格式使代码对整个开发小组来说可读 5.1命名规范 我们将用微软的匈牙利命名法规范标识符(见附录A),我们还将以本文为实例表明怎样在字母文本中加入匈牙利标记(tag).虽然你不一定必须在文件中加入匈牙利标记,但在类定义和变量声明中使用此法是有帮助的. 使用匈牙利法时,要选取合适的缩写.如果你想实际要定义一个指针,就不要说它是整数指针,而要称为单元索引(cell index).转换缩写标示要合适且前后一致.对实际用到的全局变量,在变量类型标示(tag)之前加前缀v,这样整体上才能清晰. 除了匈牙利法规范,我们还要在从DLLs中导出的大多数标示符前加标准前缀MSO(Microsoft Office).这样应用程序可方便地知道某个函数从何而来并可防止命名冲突.这个法则的唯一例外是在定义接口成员函数名和它们的参数时.因为它们没有适用范围的限制.这个MSO前缀在普通匈牙利标示(tag)之前,它的大小写取决于标示符的类型.(例如:函数用Mso,类定义用MSO,常量用mso).是带有前缀MSO的类的实例的变量和参数命名一般不用带MSO,因为这通常没必要(除非要明确特定的类),还容易混淆名字.而且,在函数内部用到的类的匈牙利标示同类定义一样也不要用mso.(见下面的例子) COM接口命名以IMso为前缀.指向接口的变量以pi为前缀(pointer to interface)加接口名的短缩写(用每个单词的第一个字母是个好方法).不带mso的变量见下面的例子. 下面的例子是不同的标示符的前缀 void * MsoPvAlloc(int cb);// 导出的 API 有 Mso MSOTBCR tbcr; // 导出的类有 MSO,但变量没有 #define msotbbsPushed 1 // 枚举型常量有 mso 和其他标示 #define msoCUsersMax 99 // 一般常量是 mso 加匈牙利名 IMsoToolbarSet *pits; // 接口有 IMso, 变量没有 pits-FUpdate(); // 接口的成员只有匈牙利名 pit-PitsGetToolbarSet(); // 返回 IMsoToolbarSet的接口成员 对类型定义的附加注意点是,它们需在导出头部中最小化.在可能的情况下,尽可能地使用Windows预定义的类,如BOOL,RECT(见基本数据类一章).而且,不要为简单枚举型定义类,就用int然后用#define定义常量.常量除了有mso前缀,还需有意义的标示(如msobbsPushed).对C++的数据成员(在我们的实现之内),我们应当用m_name的形式,这样容易辨认局部变量,也有利于使用匈牙利命名(name部分是普通的匈牙利名常常和参量和局部变量重复).本规则的一个例外是类的静态成员,应使用s_name的形式,这样使静态(全局)属性更清晰. 总结: 用匈牙利命名规则.使用定义匈牙利标识且用合适的缩写表示.将所有新的标示加入匈牙利标示登记文件中. 用v前缀表示全局变量. 用Mso前缀在需要导出的标示符的匈牙利名之前.具体为: 1. 导出的API函数用Mso(但接口的成员函数例外) 2. 类定义用MSO(但该类的变量和参数不用) 3. 常数用MSO,在它们的枚举标示之前. 4. COM接口名用IMso.接口指针用Pi(没有mso)加接口名的简短缩写(如用每个单词的第一个字母) .在导出头中使用最小的类定义.尽可能地使用基本类,用int表示枚举型. .用m_name表示C++成员数据.用s_name表示静态类数据 5.2函数原型 总是声明函数原型这样你可以获得好的类型检测和达到警告3级的代码.把参数的名字和类型即放在声明中有放在定义中,这样容易保持两者的同步.所有的函数原型应该包括在原型前的描述原型功用和参数,返回值的注释.注释最好用一句包括所有参数名的句子完成,(每个名字有但引号括起),这好过用大段的注释且每个参数对应一行的方式.因为它可以较好地保持更新.例如: /* Return the index of the foo element at position (x, y) in the fooset at pfs, or 0 if no element is found. If more than one is found, return the index of the most recently created one. */ int IFooFromXY(