版本号 v1.00
文档名称 : C++/Java编程规范
项目名称 :
项目负责人:
编写 葛志春 2002 年 9 月 3 日
校对 年 月 日
审核 年 月 日
批准 年 月 日
开发单位 云集软件网络(中国)有限公司
目 录
1 注释规范
程序的注释量应该达到代码量的1/4 、1/3,甚至更多。尤其对一段方法的描述应该不惜多写一些文字内容来充分地说明这段方法/函数的作用,以及内部的逻辑。对其参数,返回值,抛出的异常等等情况要非常清楚的说明。
1.1 类的注释
/*******************************************************
模块名称:
模块功能:
版 本:
著 作 人:
著作日期:
该模块所需的文件:
使用说明:
主要技术说明:
参考文献:
修改历史:= = = = = = = = = = = = = = = = = = = = = = = = = =
修改日期:
修 改 人:
修改理由:
修改出处:
= = = = = = = = = = = = = = = = = = = = = = = = = =
*******************************************************/
1.2 成员变量的注释
要求被注释,以说明该变量的用途。
class ClassName : public ParentClassName
{
private:
int iDataMember1; //(该成员变量的说明)
String szDataMember2; //(该成员变量的说明)
}
1.3 方法的注释
除了指明该过程或函数的功能外,在该过程或函数中的重要方法的语句的作用都要加注(显而易见的语句除外,当然这个度是靠每个人自己把握)。如:
/** ******************************************************
返回值类型 方法/函数的名称(参数列表 … ) 抛出的异常类型 …
功能:(该方法的功能描述,内部实现逻辑的文字说明)
参数:param1:(参数说明)
param2:(参数说明)
输出:(通过按址传递输出的值,此方式传值不推荐)
返回:(该方法执行完成后返回结果)
抛出异常的说明 :
************************************************/
bool ClassName::methodName(int param1, String param2)
{
int length; //(对该局部变量的说明,前提是有说明的必要)
//(对下一条语句的说明)
if(param2 == “”)
return false;
return true;
}
1.4 其它注释
在认为需要的地方,如逻辑较密集处,业务处理关键处等。
2 命名规范
2.1 包命名规范
1.包名的字母全部小写,可用缩写,但必须基本表达该包的功能范畴。
2.2 类命名规范
1. 类名的首字母大写,随后的单词的首字母都应大写;
2. 类的名称应能基本表达该类的含义,应尽量避免缩写(约定俗成的缩写除外);
3. 对于继承JDK类的子类的名称,最好在子类名前加上父类的唯一标识,可缩写。缩写方案待定(父类为Object的除外)。
2.3 方法命名规范
1. 方法名的首字母小写,随后的单词的首字母都应大写;
2. 方法的名称应能基本表达该方法的含义,应尽量避免缩写(约定俗成的缩写除外)。
2.4 变量命名规范
1. 变量的命名应遵从: 变量名 = 变量类型 + 变量含义;
2. 变量类型的表示。基本上遵从匈牙利表示法,如下所示:
a 数组
b 布尔型
c 字符
e 枚举
cb 字节计数
cr 颜色参考值
n 带符号短整形
i 带符号整形
u 无符号整形
l 带符号长整形
ul 无符号长整形
s 字符串
sz 以零结尾的串
p 指针
np 近指针
lp 长指针
h 句柄
fn 函数变量
w 无符号整形(字 WORD)
dw 无符号长整形(双字 DWORD)
stru 结构体
类不加标识
3. 变量含义。变量的名称应能基本表达该变量的含义,应尽量避免缩写(约定俗成的缩写除外),如Meter 表示表底,Bill表示清单。变量名的首字母小写,若用多个单词表示,随后的各个单词的首字母都应大写,如meterValue 表示表底值。
4. 对于JDK的类和开发环境(JBuilder)的类的实例变量,最好在实例变量的名称前加上该类的唯一标识,可缩写。缩写方案待定。
以上命名为基本规则,在各个项目进行时,有一些各个项目具体自身的命名要求,其中包含一些缩写要求,如:项目中编号 YH 表示用户,那么变量 nameYH ,addressYH则分别可以表示用户的姓名和用户的地址。
2.5 命名示例
package domaincore.interaction.*;
import java.net.*;
public class MyNewClass extends
{
private unsigned int uOrderNO; //订单编号,类型为无符号型整数
public void addOrder(int orderNO, String orderName, Date orderDate)
{
//在此放置代码
}
}
3 代码格式规范
1. 程序段中大括符的配对最好能一目了然,错落有致。一个程序段的左右大括符必须在同一列,且和引导该程序段的语句对齐。配对的大括符中的程序段必须与引导语句缩进一个TAB(推荐为4个空格字符),这样能增强程序的可读性和可维护性,减少出错的可能性;
2. 表达式:表达式中,操作符左右的表达式与操作符留有一空格。带逗号,分号的表达式中,逗号/分号的前后也留有一空格;
3. 每个方法模块之间应留2个空行隔开以示区别。
4. 代码行的宽度设置为80个字符。
如:
public void setFlag(bool bFlag, int iOperatorID) //逗号前后空一格
{
int iSum = 0; //缩进4空格, 等号前后各一个空格
for(int i = 0; i < 10; i ++) {//分号后空一格,与前一行空一行
switch(iOperatorID) { //缩进4空格
case –1: //缩进4空格
return; //缩进4空格
case 0:
…;
break;
default:
…;
break;
} //大括号与相应的对齐
iSum += i; //操作符前后空一格
} //大括号与相应的对齐
} //大括号与相应的对齐
4 编码规范
1. 在项目开发中,对任何类的任何方法(不包含main( ))——只要是被调用的方法,都要通过某种机制来反映被调用执行后是它成功还是失败,这个机制可以是:抛出异常 或者是 用统一风格的返回值 ,如: –1表示出错,0表示成功 ;
2. 每个方法建议 < 300行,最大不能超过 500 行;
3. 底层类的方法在编写代码时要对传入的参数和理性进行各种合法性校验;
(不仅从系统的角度,而且从应用逻辑的角度进行校验)
如:
int fun( String userNO, … , )
{
//如果传入的userNO为null,则整个函数/方法程序就会崩溃
if (userNO.equals("ADMIN"))
return xx;
else
return yy
}
4. 程序要追求通俗易懂,可读性要好 如:
if ( i++ >10){
…
}
要改写成
if ( i >10) {
i++;
…
}
5. 程序中不能直接将中文字符作为字符串的内容直接输出或者写入数据库;(尤其是我们要面对简体中文和繁体中文的两种情况)
6. 应该在类的构造函数中初始化所有引用和非静态数据成员,避免在成员函数中引用未被赋初值的数据成员。不作无效的引用或指针操作;
7. 对于抛出(Exception)的程序段,一定应给予例外捕获(try… catch… finally…);
8. 一个成员函数如果是对类中的成员变量进行操作,不要以参数传递的形式对该成员变量进行操作;
9. 指针在用 new 操作符分配了内存之后若不再使用必须用 delete 操作符释放内存,并将指针赋为 NULL。不能 delete 空指针,否则会使整个程序崩溃,所以在程序中使用 delete 操作符时应考虑该指针是否有可能为空。(只针对C++程序);
10. 如果在子类中分配了内存,应该使基类的析构函数成为虚拟函数;(只针对C++程序);
11. 对于在程序中多次被引用但其值以后有可能发生变化的常量应定义成宏的形式引用(用 #define 定义宏时,宏名必须大写),如对于一个存放文件的目录,由于在程序中要多次引用到,并且随着版本的更新存放路径有可能发生变化,可作如下定义:
#define _FILE_DIR “/billing/stand/net”
这样你在每次引用该路径时只要引用宏 _FILE_DIR,编程简单,也便于以后的维护。
如果程序以后有可能移植到UNIX上,路径的分隔符最好用‘/’,应为在UNIX中路径的分隔符是‘/’,而在WIN32中‘/’及‘/’都能作为路径的分隔符,使用‘/’可以和UNIX 兼容。此外还应注意路径名的大小写,在UNIX 中路径名和分件名都是大小写敏感的。(只针对C++程序)。
12.
注: 本代码编写规范针对C++和Java编写,设计到特殊要求请参照各自项目的具体规定。