开发规范Word格式.docx
《开发规范Word格式.docx》由会员分享,可在线阅读,更多相关《开发规范Word格式.docx(9页珍藏版)》请在冰豆网上搜索。
public,protected,private,abstract,static,final,transient,volatile,synchronized,native,strictfp。
类与接口的声明顺序(可用Eclipse的source->
sortmembers功能自动排列):
1.静态成员变量/StaticFields
2.静态初始化块/StaticInitializers
3.成员变量/Fields
4.初始化块/Initializers
5.构造器/Constructors
6.静态成员方法/StaticMethods
7.成员方法/Methods
8.重载自Object的方法如toString(),hashCode()和main方法
9.类型(内部类)/Types(InnerClasses)
同等的类型,按public,protected,private的顺序排列。
1.4注释规范(DocumentConvertions)
1.4.1失效代码注释
由/*...*/界定,标准的C-Style的注释。
专用于注释已失效的代码。
1.4.2代码细节注释
由//界定,专用于注释代码细节,即使有多行注释也仍然使用//,以便与用/**/注释的失效代码分开。
classMyClass{
privateintmyField;
//Anend-linecomment.
publicvoidmyMethod{
//averyverylong
//comment.
if(condition1){
//condition1comment
...
}else{
//elsesconditioncomment
}
}
1.4.3注释的格式
注释中的第一个句子要以(英文)句号、问号或者感叹号结束。
Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。
为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法,尽量多的使用@seexxx.MyClass,@seexx.MyClass#find(String)。
Class必须以@author声明作者,体现代码责任。
但不需要声明@version与@date,由版本管理系统保留此信息。
如果注释中有超过一个段落,用<p>分隔。
示例代码以<pre></pre>包裹。
标识(javakeyword,class/method/field/argument名,Constants)以<code></code>包裹。
标识(javakeyword,class/method/field/argument名,Constants)在注释中第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。
1.4.4注释的内容
可精简的注释内容
注释中的每一个单词都要有其不可缺少的意义,注释里不写"
@paramname-名字"
这样的废话。
如果该注释是废话,连同标签删掉它,而不是自动生成一堆空的标签,如空的@paramname,空的@return。
对于API函数如果存在契约,必须写明它的前置条件(precondition),后置条件(postcondition),及不变式(invariant)。
对于调用复杂的API尽量提供代码示例。
对于已知的Bug需要声明,//TODO或//FIXME声明:
未做/有Bug的代码。
在本函数中抛出的uncheckedexception尽量用@throws说明。
1.4.5特殊代码注释
代码质量不好但能正常运行,或者还没有实现的代码用//TODO:
或//XXX:
声明
存在错误隐患的代码用//FIXME:
当API会面对不可知的调用者时,方法需要对输入参数进行校验,如不符合则抛出IllegalArgumentException,建议使用Spring的Assert系列函数。
隐藏工具类的构造器,确保只有static方法和变量的类不能被构造实例。
因为System.out.println(),e.printStackTrace()仅把信息显示在控制台,因此不允许使用,必须使用logger打印并记录信息。
在数组中的元素(如String[1]),如果不再使用需要设为NULL,否则会内存泄漏。
因此直接用Collections类而不要使用数组。
在不需要封闭修改的时候,尽量使用protected而不是private,方便子类重载。
变量,参数和返回值定义尽量基于接口而不是具体实现类,如Mapmap=newHashMap();
用double而不是Float,因为float会容易出现小数点后N位的误差。
1.5异常处理
重新抛出的异常必须保留原来的异常,即thrownewNewException("
message"
e);
而不能写成thrownewNewException("
)。
在所有异常被捕获且没有重新抛出的地方必须写日志。
--TODO
如果属于正常异常的空异常处理块必须注释说明原因,否则不允许空的catch块。
1.6代码度量
1.6.1耦合度度量
DAC度量值不要不大于7。
解释:
DAC(DataAbstractionCoupling)数据抽象耦合度是描述对象之间的耦合度的一种代码度量。
DAC度量值表示一个类中有实例化的其它类的个数。
CFO度量值不要不大于20
CFO(ClassFanOut)类扇出是描述类之间的耦合度的一种代码度量。
CFO度量值表示一个类依赖的其他类的个数。
方法度量
方法(构造器)参数在5个以内
太多的方法(构造器)参数影响代码可读性。
考虑用值对象代替这些参数或重新设计。
方法长度150行以内
CC度量值不大于10
解释:
CC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量,可以用一个方法内if,while,do,for,catch,switch,case,?
:
语句与&
&
||操作符的总个数来度量。
NPath度量值不大于200
NPath度量值表示一个方法内可能的执行路径的条数。
其他度量
布尔表达式中的布尔运算符(&
||)的个数不超过3个(III)
if语句的嵌套层数3层以内(II)
文件长度2000行以内(II)
匿名内部类20行以内(II)
太长的匿名内部类影响代码可读性,建议重构为命名的(普通)内部类。
JDK5.0规范
重载方法必须使用@Override,可避免父类方法改变时导致重载函数失效。
不需要关心的warning信息用@SuppressWarnings("
unused"
),@SuppressWarnings("
unchecked"
serial"
)注释。
1.7自动代码检查
使用Eclipse的代码校验功能已经排除了很多问题。
再配合使用Checkstyle,PMD,FindBugs三重检查,总共四层的校验涵盖了Java编码大部分的GuideLine。
如果要求不苛刻,可以只使用Eclipse搭配Checkstyle。
Eclipsecodestylesetting
在Windows->
Preferences->
Java->
CodeStyle的Formatter和Cleanup中导入tools/configures/eclipse/cleanup-profile.xml和formatter-profile.xml。
在Windows->
Preference->
Editor->
SaveAction,选择FormatSourceCode,FormateAllCodes,与OrganizeImports
修改Windows->
XML->
XMLFiles->
Editor,增加到120字符
经常性执行cleaup命令执行规则(对源码目录右键->
source->
cleanup)
2Js开发规范
2.1文件编码
统一采用UTF-8
2.2分离式脚本编程
将JS、CSS、HTML文件相互独立开。
JS开发时可按模块分为多个小文件,发布时合成一个文件。
视项目需要决定是否需要混淆。
不要写行内事件
处理,如:
<
inputtype="
button"
id="
MyButton"
onclick="
OnClickMyButton()"
>
jQuery文件放在head标签中,其他script文件放在body标签结束前。
2.3变量
变量在使用前定义,变量必须使用var定义,定义多个变量时,变量间用逗号分隔,只用一个var关键字声明。
变量尽量保持最小的生存周期。
使用字面表达式,如vara=[],不要newArray(),同样的还有{},"
string"
123,true,不要newBoolean等
2.4命名
变量名和方法应以小写字母开头,采用驼峰式命名。
如:
getByClass
全局变量(常量)全部大写,尽量减少全局变量的使用。
构造函数(类)首字母大写。
变量名尽量用缩写,避免冗长多余。
如果表达意思不清除,也可以写完整的单词。
2.5函数
采用1个tab键缩进(或4个空格)。
每行分号最好不能省略。
If,else,while等复合语句不能省略{}。
每行一条语句,尽量避免每行超过80个字符。
尽量少用闭包。
2.6注释
多写注释便于维护,尽量使用单行注释。
注释应在必要的地方添加,避免无意义的注释.
超过10行的方法需要添加注释其功能
能用英文注释,尽量不要使用中文注释
2.7其他
尽量避免使用continue、eval语句。
代码中能用jQuery方法的,尽量使用jQuery,不使用JavaScript原生方法。
在document.ready后再去执行JS代码。
$(function(){……})。
应该尽量避免复杂的条件表达式,通过临时的bool变量。
混淆规范,目前由于为了调试方面,我们这边都没做混淆,在一些需要特别保密的代码,可以考虑此方法
建议统一采用YUICompressor做为JS与CSS的混淆工具。
Windows用户可以使用淘宝UED封装的TBCompressor,在右键菜单中添加了快捷方式,非常
方便。
3Jsp开发规范
3.1数据/内容显示页
名词,多个单词用下划线分隔,要求能说明显示内容的信息,为避免冲突,可加上“_list”。
例如:
new_message.html或my_file_list.jsp
3.2操作处理页
命名格式:
名词_下划线_动词,例如:
file_delete.jsp。
3.3含frame页面
<
frameset>
中<
frame>
的name属性命名的格式是①xxx._②xxx_③xxx
①xxx部分用来标识当前页面隶属于整个系统中的哪一功能模块。
如:
属于ebwebmail则被表示为ebwebmail,其它情况依次类推。
②xxx部分标识当前页面所要完成的功能。
完成用户登录的功能则被标识为login,其它情况依次类推。
③xxx部分用来用来表示页面在浏览器窗口所处的位置。
处于浏览器窗口的顶部则标识为top,其它情况依次类推。
ebwebmail_inbox_top.jsp
src属性相应的文件名根据情况建议在原命名规范上用下划线加上所处窗口的位置。
3.4javascript脚本方法
脚本函数都以①xxx_②xxx的方式命名。
①xxx对应页面隶属的模块。
②xxx表示函数所要实现的功能(动宾结构),多个单词用下划线连接。
ebwebmail_send_mail()
模块通用的脚本函数必须集合于一个js文件中,在页面上通过<
scriptlanguage=”javascript”src=”url”>
/script>
形式导入。
js文件名命名使用模块名,例如:
ebwebmail.js。
如果项目已经提供了公共js脚本,则优先使用公共js脚本中提供的函数。
所有定义方法的<
script>
元素定义在<
head>
/head>
中或<
/body>
后。
3.5javascript脚本内部变量与参数
单词之间用下划线分隔且全部小写,例如:
varfile_size。
3.6<
form>
表单name属性
统一以“form_”开头,其后加该表单所需收集的信息的作用或动作,例如:
form_file_upload或form_send_mail。
3.7表单elements
表单element的名称以element需收集的信息标示命名,单词之间使用下划线分隔且全部小写,例如:
inputtype=”text”name=”username”>
inputtype=”radio”name=”file_type”>
textareaname=”content”rows=”5”cols=”40”>
另:
一定要写JavaScript来验证表单内容
3.8cookie命名
模块名_存储信息名词(多个单词用下划线分隔),全部大写,例如:
EBWEBMAIL_SORT_TYPE。
3.9window.open中name参数的命名
javascript的window.open方法中有一个name的参数,浏览器约定同样的名字的窗口只能打开一个,如果程序间名字重复将相互冲突。
如果不限制打开窗口数,可以指定‘’或“”(不是null),否则需要加上模块名,例如ebwebmail_viewmail。
3.10Jsp头格式
jsp头部一般需要遵循以下格式:
%@pagecontentType="
text/html;
charset=ISO8859_1"
errorPage="
/error.jsp"
buffer="
128kb"
%>
如果需要import包。
则:
%@pageimport="
java.util.Vector,javax.mail.*,mon.*"
//一般jsp都需要防止缓存,这点可以在filter中完成
示例代码如下
response.setHeader("
Pragma"
"
No-cache"
);
Cache-Control"
no-cache"
Expires"
0"
3.11html格式
html头一般需要遵循以下格式:
metahttp-equiv="
Content-Type"
content="
charset=gb2312"
title>
sometitle<
/title>
linkrel="
stylesheet"
href="
some.css"
type="
text/css"
scriptlanguage="
javascript"
//somejavascript
注意:
必须指定一个有意义的<
,严禁出现“Untitled”或“未命名”之类的<
。
所有html标签使用小写
html页面一般需要设置一个背景色(一般是#FFFFFF)。
3.12html语法校验
所有的jsp/html页面需要能够使用DreamWeaver正确打开(即html语法正确,没有错误的标记)。
3.13注释一般不使用html注释,
除非是有必要让最终用户看到的内容。
对于包含JSP代码的html块,必须使用JSP注释。
对于没有必要的注释,在发行版本中必须移除。
3.14form属于域的maxlength
对于text类型的输入域,必须根据数据库字段的长度设置相应的maxlength,例如数据库类型是VARCHAR(64),那么maxlength是32(因为中文浏览器对于中文也认为是一个字符)。