编程规范.docx
- 文档编号:29675790
- 上传时间:2023-07-26
- 格式:DOCX
- 页数:26
- 大小:26.43KB
编程规范.docx
《编程规范.docx》由会员分享,可在线阅读,更多相关《编程规范.docx(26页珍藏版)》请在冰豆网上搜索。
编程规范
开发规范
北京国能科诺公司
目录
1.1.目的3
1.2.适用范围3
1.3.术语3
2.Java源文件3
2.1.源文件概述3
2.2.源文件的组成3
2.2.1.开头注释3
2.2.2.包和引入语句4
2.2.3.类、接口声明4
3.命名规则5
4.排版6
4.1.缩进6
4.2.行长6
4.3.换行6
4.4.空行8
4.5.空格8
5.注释9
5.1.实现注释9
5.1.1.块注释10
5.1.2.单行注释10
5.1.3.尾端注释10
5.1.4.行末注释11
5.2.文档注释11
6.声明12
6.1.变量声明12
6.2.类、接口声明13
7.语句14
8.编程惯例17
9.注意事项19
10.代码范例19
11.参考文献21
前言
1.1.目的
软件开发中采用统一的编程规范的目的是改善程序的可读性,方便开发人员和维护人员理解代码。
同时还有助于避免某些错误的发生。
1.2.适用范围
本规范适用于公司Java编程人员;并且每人必须遵守。
否则不能达到统一规范的目的。
1.3.术语
本规范涉及的Java语言术语请参考有关Java语言规范的文献。
2.Java源文件
2.1.源文件概述
Java源程序文件名使用的扩展名是.java。
一个源文件由被空行分割而成的段落以及标识每个段落的可选注释组成。
每个Java源文件要仅包含一个单一的类或接口。
避免使用内部类和匿名类。
每个源文件不要超过2000行,否则难以阅读。
2.2.源文件的组成
Java源文件通常依次由以下几个部分组成:
-开头注释
-包和引入语句
-类、接口声明
2.2.1.开头注释
所有的源文件都应该在开头有一个C语言风格的注释,其中列出文件名、版本信息、日期和版权声明:
/**
*-----------------------------------------------------------------
*Copyright(c)2010,AllRightsReserved.
*Useissubjecttostrictlicensingterms.
*-----------------------------------------------------------------
*
*@author:
创建者创建日期
*@brief:
类功能描述
*@log:
修改日志(修改人修改功能描述修改日期)
*/
2.2.2.包和引入语句
在多数Java源文件中,第一个非注释行是包语句。
在它之后换行后可以跟引入语句,其中引入包内的文件最好直接指明,而不用*代替。
例如:
packagejava.awt;
(可取)
importjava.util.ArrayList;
importjava.awt.peer.CanvasPeer;
(避免)
importjava.util.*;
importjava.awt.peer.*;
2.2.3.类、接口声明
下表描述了类和接口声明的各个部分以及它们出现的先后次序:
类/接口声明的各部分
注解
1
类/接口文档注释
开头注释
2
类或接口的声明
3
类/接口实现的注释(/**……*/)如果有必要的话
该注释应包含任何有关整个类或接口的信息,而这些信息又不适合作为类/接口文档注释。
4
类的(静态)变量
首先是类的公共变量,随后是保护变量,再后是包一级别的变量(没有访问修饰符),最后是私有变量。
5
实例变量
首先是公共级别的,随后是保护级别的,再后是包一级别的(没有访问修饰符),最后是私有级别的。
6
构造器
7
方法的文档注释
/**fn-hd
*rem:
函数功能描述
*par:
参数描述
*par:
参数描述
*author:
xiangwei.wang10-23-2006
*log:
修改日志
*/
8
方法
这些方法应该按功能而非作用域或访问权限分组。
例如,一个私有的类方法可以置于两个公有的实例方法之间。
其目的是易于阅读和理解代码。
3.命名规则
标识符要由能表达该标识符含义的英语单词组成。
避免使用汉字、汉语拼音或其他无意义的字符串。
标识符类型
命名规则
例子
包(Packages)
为了使包名唯一,包名的前缀应是全部小写的ASCII字母并且是一个顶级域名,通常是com,edu,gov,mil,net,org,或1981年ISO3166标准所指定的标识国家的英文双字符代码。
包名的后续部分根据不同机构各自内部的命名规范而不尽相同。
这类命名规范可能以特定目录名的组成来区分部门(department),项目(project),机器(machine),或注册名(loginnames)。
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
类(Classes)
-类名是一个名词。
-采用大小写混合的方式,每个单词的首字母大写。
-尽量使类名简洁且有意义。
-使用完整单词,避免缩写词(除非该缩写词被更广泛使用,如URL,HTML)。
classRaster;
classImageSprite;
接口(Interfaces)
与类名规则相同。
interfaceRasterDelegate;
interfaceStoring;
方法(Methods)
-方法名是一个动词。
-采用大小写混合的方式,第一个单词的首字母小写,其后单词的首字母大写。
run();
runFast();
getBackground();
变量(Variables)
-变量(包括实例变量、类变量和类常量)采用大小写混合的方式。
以“m_”开头,接着的第一个单词的首字母小写,其后单词的首字母大写。
-多个变量写在一起时,上下变量之间的变量类型、变量名和变量初始值都应该对齐。
-变量名不应以下划线“_”或美元符号(“$”)开头(尽管这在语法上是允许的)。
-变量名要简短、易记且能表达变量的用途。
-尽量避免单个字符的变量名,除非是一次性的临时变量。
临时变量通常被取名为i、j、k、m和n,一般用于整型;c、d、和e,一般用于字符型。
Stringm_name=“”;
intm_testID=0;
常量(Constants)
类常量声明,应该全部大写,单词间用下划线连接。
staticfinalintMIN_WIDTH=4;
staticfinalintMAX_WIDTH=999;
staticfinalintGET_THE_CPU=1;
4.排版
4.1.缩进
4个空格常被作为缩进排版的一个单位。
不要求一定用空格或Tab键。
但注意Tab键为8个空格宽。
有些编辑器可以把Tab键设置定成显示4个空格或转换为4个空格。
4.2.行长
尽量避免一行的长度超过120个字符,因为很多终端和编辑工具不能很好处理。
4.3.换行
当一个表达式无法容纳在一行内时,可以依据如下一般规则断开:
-在一个逗号后面断开
-在一个操作符前面断开
-选择较高级别(higher-level)的断开,而非较低级别(lower-level)的断开
-新的一行应该与上一行同一级别表达式的开头处对齐
-如果以上规则导致代码混乱或者使代码都堆挤在右边,那就代之以缩进8个空格。
以下是断开方法调用的一些例子:
someMethod(longExpression1,longExpression2,longExpression3,
longExpression4,longExpression5);
var=someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));
以下是两个断开算术表达式的例子。
前者更好,因为断开处位于括号表达式的外边,这是个较高级别的断开。
longName1=longName2*(longName3+longName4-longName5)
+4*longname6;//可取
longName1=longName2*(longName3+longName4
-longName5)+4*longname6;//避免
以下是两个缩进方法声明的例子。
前者是常规情形。
后者若使用常规的缩进方式将会使第二行和第三行移得很靠右,所以代之以缩进8个空格
//通常的段开规则
someMethod(intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother)
{
...
}
//缩进8个空格
privatestaticsynchronizedhorkingLongMethodName(intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother)
{
...
}
这里有三种可行的方法用于处理三元运算表达式:
alpha=(aLongBooleanExpression)?
beta:
gamma;
alpha=(aLongBooleanExpression)?
beta
:
gamma;
alpha=(aLongBooleanExpression)
?
beta
:
gamma;
4.4.空行
空行将逻辑相关的代码段分隔开,以提高可读性。
下列情况应该使用两个空行:
-一个源文件的两个片段之间
-类声明和接口声明之间
下列情况应该使用一个空行:
-两个方法之间
-方法内的局部变量和方法的第一条语句之间
-块注释或单行注释之前
-一个方法内的两个逻辑段之间
4.5.空格
下列情况应该使用空格:
-一个紧跟着括号的关键字应该被空格分开,例如(“■”代表空格):
while■(true)
{
...
}
注意:
空格不应该置于方法名与其左括号之间。
这将有助于区分关键字和方法调用。
-参数列表中逗号的后面要有一个空格
someMethod(intanArg,■ObjectanotherArg,■StringyetAnotherArg)
{
}
-所有的二元运算符,除了".",应该使用空格将之与操作数分开。
一元操作符和操作数之间不加空格,比如:
负号("-")、自增("++")和自减("--")。
例如:
a■+=■c■+■d;
a■=■(a■+■b)■/■(c■*■d);
while■(d++■==■s++)
{
n++;
}
printSize("sizeis"■+■foo■+■"\n");
-for语句中的表达式应该被空格分开,例如:
for■(expr1;■expr2;■expr3)
5.注释
Java程序有两类注释:
实现注释(implementationcomments)和文档注释(documentcomments)。
使用/*...*/和//界定的注释。
文档注释是Java独有的,并由/**...*/界定。
文档注释可以通过javadoc工具转换成HTML文件。
实现注释用以注释代码或者实现细节。
文档注释不描述实现细节,而是比实现更高层的角度描述代码的规范。
它可以被那些手头没有源码的开发人员读懂。
注释应给出代码的总括,并提供代码自身没有提供的附加信息。
注释应该仅包含与阅读和理解程序有关的信息。
例如,相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。
在注释里,对设计决策中重要的或者不是显而易见的地方进行说明是可以的,但应避免提供代码中己清晰表达出来的重复信息。
冗余的注释很容易过时。
通常应避免那些代码更新就可能过时的注释。
注意:
频繁的注释有时反映出代码的低质量。
当觉得被迫要加注释的时候,考虑一下重写代码使其更清晰。
注释不应写在用星号或其他字符画出来的大框里。
注释不应包括诸如制表符和回退符之类的特殊字符。
5.1.实现注释
程序可以有4种实现注释的风格:
块、单行、尾端和行末。
5.1.1.块注释
块注释通常用于提供对文件,方法,数据结构和算法的描述。
块注释被置于每个文件的开始处以及每个方法之前。
它们也可以被用于其他地方,比如方法内部。
在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。
块注释之前应该有一个空行,用于把块注释和代码分割开来,比如:
/*
*Hereisablockcomment.
*/
5.1.2.单行注释
短注释可以写在一行内,并与其后的代码具有一样的缩进层级。
如果一个注释不能在一行内写完,就该采用块注释。
单行注释之前应该有一个空行。
以下是一个Java代码中单行注释的例子:
if(condition)
{
/*Handlethecondition.*/
...
}
5.1.3.尾端注释
极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。
若有多个短注释出现于大段代码中,它们应该具有相同的缩进。
以下是一个Java代码中尾端注释的例子:
if(a==2)
{
returnTRUE;/*specialcase*/
}
else
{
returnisPrime(a);/*worksonlyforodda*/
}
5.1.4.行末注释
注释界定符"//",可以注释掉整行或者一行中的一部分。
它一般不用于连续多行的注释文本;然而,它可以用来注释掉连续多行的代码段。
以下是所有三种风格的例子:
if(foo>1)
{
//Doadouble-flip.
...
}
else
{
returnfalse;//Explainwhyhere.
}
//if(bar>1)
//{
//
////Doatriple-flip.
//...
//}
//else
//{
//returnfalse;
//}
5.2.文档注释
文档注释描述Java的类、接口、构造器,方法,以及字段(field)。
每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类、接口或成员。
该注释应位于声明之前:
/**
*TheExampleclassprovides...
*/
publicclassExample{...
注意最顶层的类和接口是不缩进的,而其成员是缩进的。
描述类和接口的文档注释的第一行(/**)不需缩进;随后的文档注释每行都缩进1格(使星号纵向对齐)。
成员,包括构造函数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。
若想给出有关类、接口、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现块注释或紧跟在声明后面的单行注释。
例如,有关一个类的实现的细节,应放在紧跟类的声明后面的实现块注释中,而不是放在文档注释中。
文档注释不能放在一个方法或构造器的定义块中,因为Java会将位于文档注释之后的第一个声明与其相关联。
若想了解更多,参见"HowtoWriteDocCommentsforJavadoc",其中包含了有关文档注释标记的信息(@return,@param,@see):
若想了解更多有关文档注释和javadoc的详细资料,参见javadoc的主页:
6.声明
6.1.变量声明
-推荐一行一个声明,因为这样以利于写注释。
即,
intlevel;//indentationlevel
intsize;//sizeoftable
要优于,
intlevel,size;
-不要将不同类型变量的声明放在同一行,例如:
intfoo,fooarray[];//避免!
注意:
上面的例子中,在类型和标识符之间放了一个空格,另一种被允许的替代方式是使用制表符:
intlevel=0;//indentationlevel
intsize=0;//sizeoftable
ObjectcurrentEntry=null;//currentlyselectedtableentry
-尽量在声明局部变量的同时初始化。
除非变量的初始值依赖于某些先前发生的计算。
-只在代码块的开始处声明变量。
(一个块是指任何被包含在大括号"{"和"}"中间的代码。
)不要在首次用到该变量时才声明。
这会把注意力不集中的程序员搞糊涂,同时会妨碍代码在该作用域内的可移植性。
voidmyMethod()
{
intint1=0;//在方法块的开始
if(condition)
{
intint2=0;//在if块的开始
...
}
}
该规则的一个例外是for循环的计数变量
for(inti=0;i { ... } -避免声明的局部变量覆盖上一级声明的变量。 例如,不要在内部代码块中声明相同的变量名: intcount; ... myMethod() { if(condition) { intcount=0;//避免! ... } ... } 6.2.类、接口声明 当编写类和接口是,应该遵守以下格式规则: -在方法名与其参数列表之前的左括号"("间不要有空格 -左大括号"{"另起一行(注: 另外一种风格是"{"位于声明语句同行的末尾。 本规范推荐另起一行) -右大括号"}"另起一行,与相应的声明语句对齐,每个块的左、右大括号在同一列 classSampleextendsObject { intivar1; intivar2; Sample(inti,intj) { ivar1=i; ivar2=j; } intemptyMethod() { } ... } -方法与方法之间以空行分隔 7.语句 -每行至多包含一条语句,例如: argv++;//可取 argc--;//可取 argv++;argc--;//避免! -复合语句是包含在大括号中的语句序列,形如"{语句}"。 被大括号括起来的语句应该缩进一个层次。 左大括号"{"另起一行,与复合语句首行对齐;右大括号"}"另起一行并与复合语句首行对齐。 在if-else或for等控制结构中,如果某一部分只有一条语句,也要用大括号括起来。 这样便于添加语句而无需担心由于忘了加括号而引入bug。 例如: if(condition) { statements; } if(condition) { statements; } else { statements; } if(condition) { statements; } elseif(condition) { statements; } else { statements; } 注意: if语句总是用"{"和"}"括起来,避免使用如下容易引起错误的格式: if(condition)//避免! 省略了{}! statement; 一个for语句应该具有如下格式: for(initialization;condition;update) { statements; } 一个空的for语句(所有工作都在初始化,条件判断,更新子句中完成)应该具有如下格式: for(initialization;condition;update); 当在for语句的初始化或更新子句中使用逗号时,避免因使用三个以上变量,而导致复杂度提高。 若需要,可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。 一个while语句应该具有如下格式 while(condition) { statements; } 一个空的while语句应该具有如下格式: while(condition); 一个do-while语句应该具有如下格式: do { statements; }while(condition); 一个switch语句应该具有如下格式: switch(condition) { caseABC: statements; /*fallsthrough*/ caseDEF: statements; break; caseXYZ: statements; break; default: statements; break; } 每当一个case顺着往下执行时(因为没有break语句),通常应在break语句的位置添加注释。 上面的示例代码中就包含注释/*fallsthrough*/。 一个try-catch语句应该具有如下格式: try { statements; } catch(ExceptionClasse) { statements; } 一个try-catch语句后面也可能跟着一个finally语句,不论try代码块是否顺利执行完,它都会被执行。 try { statements; } catch(ExceptionClasse) { statements; } finally { statements; } 8.编程惯例 -尽量把实例或类变量声明为私有。 通过定义“getVarName”、“setVarName”实现读、写私有变量。 但当类仅作为数据结构没有行为时,把类的实例变量声明为公有是合适的。 -避免用一个对象访问一个类的静态变量和方法。 应该用类名替代。 -避免使用“魔术数字”—直接写在程序里的数字。 要定义常量,并在整个程序中都采用常量标识符。 这样可使程序更易理解和维护。 但位于for循环中等语句中作为计数器值的数字-1、0和1例外。 -避免在一个语句中给多个变量赋相同的值,否则可读性差。 例如: fooBar.fChar=barFoo.lchar
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 编程 规范
![提示](https://static.bdocx.com/images/bang_tan.gif)