JAVA编码规范 JCS.docx
- 文档编号:18363526
- 上传时间:2023-08-16
- 格式:DOCX
- 页数:18
- 大小:23.31KB
JAVA编码规范 JCS.docx
《JAVA编码规范 JCS.docx》由会员分享,可在线阅读,更多相关《JAVA编码规范 JCS.docx(18页珍藏版)》请在冰点文库上搜索。
JAVA编码规范JCS
JAVA编码规范
JavaCodingSpecification
编号:
JCS
版本1.0
作者:
日期:
审批:
日期:
变更记录
日期
版本
变更说明
作者
1.0
创建
目录
1导言5
1.1目的5
1.2范围5
1.3角色和职责5
1.4术语定义5
2格式6
2.1.缩进6
2.2间隔7
2.3空行8
2.4类成员的摆放顺序8
2.5文件格式(FileFormat)8
2.6行最大长度9
2.7括号9
3命名规则10
3.1类和接口10
3.2包10
3.3get和set方法(属性的定义)10
3.4变量11
3.4.1普通变量:
11
3.4.2常用对象变量11
3.4.3StaticFinal变量的命名11
3.4.4临时变量12
4注释13
4.1要求13
4.2JavaDoc说明13
4.3类14
4.4方法15
4.5代码的自我说明16
5编码17
5.1不要使用的结构17
5.1.1“do…while”17
5.1.2"return"(建议,尽量避免,也可以使用)17
5.1.3"continue"17
5.1.4"break"17
5.2不要混合使用递增运算符和递减运算符17
5.3变量初始化18
5.4魔鬼数字/字符18
5.5范围(scope)18
1导言
Java语言给了程序员充分的空间随意编写自己的代码,但也正是因为如此,一个程序员自己编写的代码往往不能被别的程序员很好的阅读和理解。
1.1目的
本文档旨在提供一个编码的标准,以便所有Java代码在产生的一开始就能够在整个开发团队中保持一致,从而能够更好的阅读和修改代码。
1.2范围
本文档适用于软通动力公司项目开发团队的所有成员,为了使项目的后期维护和修改变的容易,在每个项目开发中一定要遵守本文档中的规定术语定义
1.3角色和职责
●编码负责人:
本规范在具体项目中执行监督负责人。
通过实施SourceReview制度,编程人员在完成自己的一个模块并提交测试前,由编码负责人进行SourceReview,不符合本编程规约的程序一律打回,重新修改,即编码人你认为自己的程序没有任何的功能问题。
●编码人员
本规范的遵守者。
1.4术语定义
●Logger-系统进行日志输出了类,为引用第三方(ApacheGroup)的输出类,具体用法见Log输出规范的说明。
2格式
2.1.缩进
所有的缩进皆为4个空格。
对应的括号通常在同一列的位置上。
例如:
voidfoo()
{
while(bar>0)
{
Logger.debug();
bar--;
}
if(oatmeal==tasty)
{
Logger.debug("Oatmealisgoodandgoodforyou");
}
elseif(oatmeal==yak)
{
Logger.debug("Oatmealtasteslikesawdust");
}
else
{
Logger.debug("tellmepleezewhatizdis'oatmeal'");
}
switch(suckFactor)
{
case1:
Logger.debug("Thissucks");
break;
case2:
Logger.debug("Thisreallysucks");
break;
default:
Logger.debug("whatever");
break;
}
}
1).所有的缩进是由"Space(空格)键"形成的,而不是"Tab键"。
2).所有的if、while和for语句中的"状态"内容必须用括号括起来,就算只有一个状态。
if(superHero==theTick)
{
Logger.debug("Spoon!
");
}
2.2间隔
1).所有的标识符都必须被空白字符包围。
inttheTick=5;
if(theTick==5)
这么做唯一可能成为麻烦的是复杂的布尔分析影响了清晰度,例:
if((hero==theTick)&&((sidekick==arthur)||(sidekick==speak)))
不如这样:
booleanisTickSidekick=((sidekick==arthur)||(sidekick==speak));
if((hero==theTick)&&isTickSidekick)
{
…
}
2).然而也有一些例外的情况,见下表:
例外情况
原由
正确示例
错误示例
方法名
习惯写法是在所有方法名之后直接跟上一个左括号
foo(i);
start();
args[0];
tens[i];
数组
习惯写法是在所有数组名之后直接跟上一个左方括号
args[0];
tens[I];
args[0];
tens[i];
自加、自减运算符
习惯写法是在所有一元运算符前面或后面直接加上操作数
++count;i--;
++count;i--;
造型运算符
习惯写法是所有造型都不加空格
(MyClass)v.get(3);
(MyClass)v.get(3);
(MyClass)v.get(3);
2.3空行
应该时不时的在各方法之间加入一些空格行来分割大段的代码;
还应该在方法与方法之间加入一两行的空格行。
2.4类成员的摆放顺序
classOrder
{
1.finalattributes
2.attributes
3.constructors
4.methods
}
必须保持private方法被放置在使用该方法的其他方法之上,而在构造器(constructor)之下,即使该构造器有可能调用这些private方法。
2.5文件格式(FileFormat)
"package"必须总保持第一个出现;
"import"其次;
再次,任何非javadoc的注释;
然后是javadoc类文件
最后便是类。
注意:
一个文件(File)只能有一个类,内部类除外。
示例:
packagemisc;
importjava.io.*;
import.*;
/**thisclassdoescoolstuff
*@authorJoeProgrammer
*/
classSpaceMonkey
{
...
}
2.6行最大长度
不要让一行代码的长度超过120个字符,最好是低于80个字符。
如果代码开始向右延伸得很长,你就应该考虑把它分割成更多的方法。
2.7括号
使用括号的目的必须是在表达上不但能够标明优先顺序,而且有助于使表达更简单明了。
另外,如果某一段代码有可能产生歧义,也需加括号。
3命名规则
所有的标识符只能用字母(A-Z或a-z)和数字(0-9)。
不能有货币符号或者其它非ASCII字符。
3.1类和接口
所有类和接口标识符将都使用混合"格"表示。
每个名称中的每个单词首字母必须大写,同时这个名称的首字母也必须大写;其它的字母均小写,除了缩写词之外(它们必须全部大写)。
示例:
Customer
SalesOrder
TargetURL
URLTarget
3.2包
所有包名只能用小写字母。
尽量别使包名长度超过8个字符,应该避免使用多个词作为包名。
示例:
common
core
lang
3.3get和set方法(属性的定义)
用于设置对象状态的方法必须在方法名前面加一个前缀set;用于检索一个布尔类型对象状态的方法必须在方法名前面加一个前缀is;而用于检索其它类型对象状态的方法则必须在方法名前面加上get。
示例:
setEnabled()
getName()
isEnabled()
3.4变量
3.4.1普通变量:
变量的命名应尽可能采用见名知义,基本命名规则如下:
变量名=变量前缀+变量含义
变量前缀遵循匈牙利命名规则,定义如下:
类型
前缀
short
s
int
n
char
ch
double
d
boolean
b
long
l
float
f
3.4.2常用对象变量
类型
前缀
String
str
Vector
v
HashMap
hm
Hashtable
ht
Date
dt
Timestamp
ts
Collection
coll
Iterator
iter
List
lst
Object[]
aryObj
3.4.3StaticFinal变量的命名
StaticFinal变量的名字应该都大写,每个单词之间用”_”连接,并且指出完整含义。
3.4.4临时变量
一般临时变量没有具体的意思,所以临时变量名为:
临时变量名=变量前缀+(Temp或Tmp);
其中有一些C语言延续下来的常见临时变量也可以接受:
如i,j,k一般用于表示一个临时整型变量。
4注释
大部分注释尽量用"//";对于所有的javadoc的注释则用"/***/";而临时对代码块进行的注释尽量用"/**/"。
4.1要求
1、程序中注释行应不少程序代码行的40%;
2、类、方法、变量必须注释说明;
3、注释内容应根据客户要求的语言进行,原则上,除常量、变量、变量类型等以外的说明尽可能采用中文注释;
4.2JavaDoc说明
1).JavaDoc注释将用于说明那些被其它类调用的类、属性和方法。
这些注释必须出现在所要说明的各项之前。
2).JavaDoc注释一般不会用于说明一些显而易见的方法,例如:
publicstaticvoidmain(String[]args)或publicintgetX();
3).JavaDoc注释也不用于说明一些显而易见的参数,如:
publicvoidsetX(intnewX);
4).诸如servlet和EJB等那些没有被其它类调用的类,也不必加JavaDoc注释。
把源码上交给整个团队之前,必须先经过JavaDoc处理,并全面检查处理结果,以确定说明文字确实可读而且清楚明白。
如果JavaDoc注释能够在一行内写下,则格式应该象下面这样:
/**Usedtomarkspots*/
intx;
如果JavaDoc注释内容在一行内容纳不下,则其格式应该象下面这样:
/**Sethowmuchtogrowwhengrowthisneeded.
*Smallervalueswillusuallysavememory,butfrequent
*reallocationmaytakealotoftime.
*@paramHowMuchThenumberofextraintstoallocatewhen
*memoryreallocationisrequired.Valuesmustbegreaterthan
*zero.
*/
publicvoidsetExtra(intHowMuch)
{
……
}
注意:
HTML标签
和
的作用。迫使一段代码进行分行,而
…则让块文字以特定的字体表现出来并且保留所有的空格字符。JavaDoc还允许使用其它的HTML标签,但是禁止使用header标签(如
,
等)你可以用..加黑文字,也可以用..使文字变为斜体。
注意:
JavaDoc把每个JavaDoc注释的第一行划分出来以用于放置"内容表"。
如何标识出这部分内容的结束边界线呢?
JavaDoc定义这个标志为"一个句号后跟一个空格"。
其它如"一个问号后跟一个空格"或"一个句号后跟一个
标签"都不是结束标志。
如果在句号和
之间加一个空格,那么就有结束标志产生了。
4.3类
类的JavaDoc说明文件必须包括以下内容:
(1)简要的提纲
(2)详细的描述
(3)使用该类的示例代码段
(4)用@author标签列出作者
注意:
由于JavaDoc中一个"功能(feature)"限制,所有示例代码的每行前面必须加入一个星号,以便保存每行的缩进。
例如:
/**Avectorclassoptimizedforworkingwithints.
*LiketheVectorobject,exceptratherthantrackingadynamic
*arrayofpointerstodifferentobjects,thisissimplya
*dynamicarrayofints.Theadvantageisspeedandmemory
*savings.
*Example:
*
*//reportlongestlines
*TextFileInf=newTextFileIn("blather.txt");
*IntVectorv=newIntVector();
*intlongestLine=0;
*booleandone=false;
*while(!
done)
*{
*Strings=f.readLine();
*if(s==null)
*{
*done=true;
*}
*else
*{
*intsLength=s.length();
*if(sLength>longestLine)
*{
*longestLine=sLength;
*}
*v.append(sLength);
*}
*}
*f.close();
*Logger.debug("Thelongestlinesareonlinenumbers:
");
*for(inti=0;i
*{
*if(v.get(i)==longestLine)
*{
*Logger.debug(i);
*}
*}
*
*@authorAdamBaum
*@authorJustinCase
*/
publicclassIntVector
{
……
}
4.4方法
方法的JavaDoc说明文档必须包含以下内容:
(1)简要的提纲;
(2)详细的描述(如果有必要在简要提纲内补充说明某些内容的话);
(3)用JavaDoc的@param标签列出所有参数(如果有参数的话);
(4)用JavaDoc的@return标签返回出方法的值列表(如果需要返回值的话);
(5)用JavaDoc的@exception标签列出所有异常(exception)(如果有异常抛出的话)
示例:
/**Getacopyofoneint.
*Retrieveanintrelativetotheindexprovided.
*@paramIndexWhichint(0isthefirstint).
*@returnTheretrievedintorzeroifIndexisoutsideof0..length.
*/
publicintget(intIndex)
{
}
4.5代码的自我说明
"傻子写计算机识别的程序;程序员写人识别的程序。
"
--MartinFowler,Refactoring:
《提高代码的设计水平》
除了要尽力用文件说明程序的复杂算法,我们还必须尽量通过多用一些标识符来使程序的算法易读。
这样有助于减少将来需要修改程序而不需修改说明文档而带来的麻烦。
/**determineifthegivenyearisaleapyear.
*TheGregoriancalendarprincipalstatesthataleapyearoccurs
*everyfourthyear,exceptevery100years,exceptevery400
*years.
*@paramyearTheyeartobetested.Makesurethisisafourdigityear!
*@returntrueif"year"isaleapyear.
*/
booleanisLeapYear(intyear)
{
booleany4=((year%4)==0);
booleany100=((year%100)==0);
booleany400=((year%400)==0);
return(y400||(y4&&!
y100));
}
5编码
5.1不要使用的结构
5.1.1“do…while”
不要用do…while循环,用while()循环
5.1.2"return"(建议,尽量避免,也可以使用)
不要在一个方法的中间使用"return","return"只能出现在一个方法的末尾。
原因:
在方法的中间使用"return"会给今后将方法拆分成几个更小的方法带来困难;而且它会迫使开发者不得不为该方法考虑多于一个的出口点。
5.1.3"continue"
决不要用"continue"。
原因:
continue会给将来把一个结构拆分成几个更小的结构或方法带来许多困难;而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。
5.1.4"break"
"break"只能用于转换状态(switchstatement)的控制。
原因:
在转换状态控制之外的情况下使用break,会给将来把一个结构拆分成几个更小的结构或方法带来许多困难;而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。
5.2不要混合使用递增运算符和递减运算符
不要混合使用递增运算符和递减运算符,
原因:
在方法调用或是数学运算中混合使用递增运算符(或递减运算符)会造成欠经验的程序员阅读的困难,他们也许会让你重写代码的。
所以,最好在递增运算符(或递减运算符)之间加上额外的行。
5.3变量初始化
最好总是在每个变量出现的时候就马上进行初始化。
最好只在需要的时候再声明(declare)一个变量,不然的话会影响代码的执行效果。
示例:
intsecondWide=12;
intfirstWide=doFoo(20,secondWide);
doBar(firstWide,secondWide);
inttotalWide=firstWide+secondWide;//很好!
5.4魔鬼数字/字符
程序中应尽可能少使用数字/字符,尽可能定义静态变量来说明该数字/字符的含义,程序中需要赋值或比较时,使用前面定义的静态变量。
以下情况例外:
Ø循环控制;
5.5范围(scope)
原则上类的成员变量必须是总是private,尽量少用protected和public,但以下情况例外:
Ø内部类的成员变量(可以为public);
Ø子类可继承的基类成员变量(可以为protected);
Ø并发控制中的信号变量(可以为public)。
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- JAVA编码规范 JCS JAVA 编码 规范