开发编码规范文档.docx

《开发编码规范文档.docx》由会员分享，可在线阅读，更多相关《开发编码规范文档.docx（16页珍藏版）》请在冰豆网上搜索。

开发编码规范文档

1Web开发规范概述

Web开发规范是针对Web系统差别于传统的软件开发，为规范前台Web页面风格以及后台Java程序编码而编写的，为了保证开发代码风格的一致性、规范性和可读性，减少后期程序维护的工作量，要求项目组各成员在进行设计的过程中必需遵守执行，如果对本规范有异议或者需要在规范中增加新的条目，请尽早提出，以利于规范的更改以及相关代码的及时更改。

定义本规范的目的是让项目中所有的文档都看起来像一个人写的，增加可读性，减少项目组中因为换人而带来的损失。

本规范并不是一定要绝对遵守，但是一定要让程序文档有良好的可读性及统一的规则，具体项目可以根据项目的实际情况对本规范进行剪裁和补充，生成项目组成员实际遵守的开发规范，以达到适应不同开发工具不同开发模式的项目。

2Web页面开发规范

页面风格规范

页面统一规范

页面风格必须保持一致，包括页面的前景色，背景色等内容，页面内容摆放遵循统一规则，对于页面风格尽可能使用CSS模式文件。

例如对于所有页面都要有“关闭”“返回”“帮助”链接：

统一在页面左上角，顺序为“关闭”、“返回”、“帮助”。

处理规则：

点击“关闭”链接，如果本页面是弹出的，则关闭本页面，否则返回到“任务列表”页面；点击“返回”链接，返回到上一个页面；点击“帮助”链接，弹出本页面的操作说明及下一步如何操作。

操作按钮规范

规范所有的按钮的展示属性，包括大小、尺寸及图标、tooltips等。

录入项目规定

所有界面的必选项目必须添加红色的“*”进行标注，并且在保存的过程中执行相应的判断并以提示信息的形式进行提示。

信息框规定，

提示信息，如必须项目

确认信息，提示用户并需要得到用户的认可

警告信息，系统处理失败需要提示用户的信息

由客户引起的失败

由应用程序引起的失败：

删除必须以确认信息的形式进行说明

成功保存处理后都必须以提示信息的方式进行提示

失败处理必须以警告信息的形式进行提示

HTML编码规范

●必须为title赋值并且在可能的情况下和页面内容中的标题一致；如果要为HTML文件加图片，图片的尺寸不能超过250*250，图片的大小不能超过30K,必须保证一个网页总长度限制在50k；必须定义每页的backgroundcolor，即使backgroundcolor为白色，也必须把它定义在标签里；

●用级联格式页（即CSS）定义显示方面的内容，例如：

字体、边框等等；用Dreamweaver或其他专业工具作为HTML的开发工具；设计以800*600作为显示器的标准；

●用IE4.0和Netscape4.0作为标准测试浏览器；尽量不用Frame；尽量避免使用动态HTML，例如：

层……

●使用封闭式标签（balancedtags）

类似于,以及这类标签，一页中只能用一次，以避免在Netscape浏览器里出现刷新问题，在被包含文件中，不允许用以上标签；源代码要格式良好（这一点尤其重要），要像其他程序源码一样有缩进；不允许使用中文全角空格，必须使用“ ”。

●Table的嵌套不要超过五层；所有内容都放至在表格中控制位置，避免用层来控制位置；

—endtableofid-->”。

例如：

……

—endtableofheader-->

在空的标签中插入空白图以避免Netscape中出现问题；

图片一定要指定尺寸大小；图片和链接都不允许用本地路径，使用虚拟绝对路径。

JSP编码规范

JSP编码规范符合Java编码规范，其余参照JSP语法规则。

JavaScript编码规范

●变量和方法首单词全部用小写字母，后面其他首字母大写。

●所有的变量都必须声明。

●每行都必须用分号“；”结尾。

●常用的一些函数归类，使用包含文件，

举例：

。

文件说明

/include/html/form.js与表单form有关的一些函数，如检查子段是否为空，检查Email格式等等。

/include/html/string.js跟字符串处理有关的函数。

3JAVA程序编码规范

程序编码规范

命名规范

Javapackage、Javaclass、javaclassmethod、Javaclass属性/变量/参数命名规则依照java的一般规则。

∙Package的命名

Package的名字应该都是由一个小写单词组成。

例子:

com.system.action系统管理部分核心业务逻辑控制类

com.system.actionForm系统管理部分数据传递actionForm类

com.system.manage系统管理部分数据库操作类

com.system.sqlObject系统管理部分sql语句处理封装类

com.system.object系统管理部分数据对象封装类

∙Class的命名

Class的名字必须由大写字母开头而其他字母都小写的单词组成。

Class名字为英文或英文简写，第一个字母必须大写，如果多个简写单词合并为一个类名称，所有简称的第一个字母必须大写

∙Class变量的命名

变量的名字必须用一个小写字母开头。

后面的单词用大写字母开头。

∙StaticFinal变量的命名

StaticFinal变量的名字应该都大写，并且指出完整含义。

∙参数的命名

参数的名字必须和变量的命名规范一致。

∙数组的命名

数组应该总是用下面的方式来命名：

String[]str;

而不是：

Stringstr[];

∙方法的参数

使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：

publicvoidsetCounter（intnewSize）{

size=newSize;

}

publicvoidsetCounter（intsize）{

this.size=size;

}

代码样式

∙版权信息

版权信息必须在java文件的开头，比如：

/**

*Copyright®2006xundeXXXCo.Ltd.

*Allrightreserved.

*/

其他不需要出现在javadoc的信息也可以包含在这里。

∙Package/Imports

package行要在import行之前，import中标准的包名要在本地的包名之前，而且按照字母顺序排列。

如果import行中包含了同一个包中的不同子目录，则允许用*来处理。

package.stats;

importjava.io.*;

importjava.util.Observable;

importhotlava.util.Application;

这里java.io.*使用来代替InputStreamandOutputStream的。

∙Class

接下来的是类的注释，一般是用来解释类的。

/**

*Aclassrepresentingasetofpacketandbytecounters

*Itisobservabletoallowittobewatched,butonly

*reportschangeswhenthecurrentsetiscomplete

*/

接下来是类定义，包含了在不同的行的extends和implements

publicclassCounterSet

extendsObservable

implementsCloneable

∙ClassFields

接下来是类的成员变量：

/**

*Packetcounters

*/

protectedint[]packets;

public的成员变量必须生成文档（JavaDoc）。

proceted、private和package定义的成员变量如果名字含义明确的话，可以没有注释。

∙存取方法

接下来是类变量的存取的方法。

它只是简单的用来将类的变量赋值获取值的话，可以简单的写在一行上。

/**

*Getthecounters

*@returnanarraycontainingthestatisticaldata.Thisarrayhasbeen

*freshlyallocatedandcanbemodifiedbythecaller.

*/

publicint[]getPackets（）{returncopyArray（packets,offset）;}

publicint[]getBytes（）{returncopyArray（bytes,offset）;}

publicint[]getPackets（）{returnpackets;}

publicvoidsetPackets（int[]packets）{this.packets=packets;}

其它的方法不要写在一行上

∙构造函数

接下来是构造函数，它应该用递增的方式写（比如：

参数多的写在后面）。

访问类型（"public","private"等.）和任何"static","final"或"synchronized"应该在一行中，并且方法和参数另写一行，这样可以使方法和参数更易读。

public

CounterSet（intsize）{

this.size=size;

}

∙克隆方法

如果这个类是可以被克隆的，那么下一步就是clone方法：

public

Objectclone（）{

try{

CounterSetobj=（CounterSet）super.clone（）;

obj.packets=（int[]）packets.clone（）;

obj.size=size;

returnobj;

}catch（CloneNotSupportedExceptione）{

thrownewInternalError（"UnexpectedCloneNotSUpportedException:

"+e.getMessage（））;

}

}

∙类方法

下面开始写类的方法：

/**

*Setthepacketcounters

*（suchaswhenrestoringfromadatabase）

*/

protectedfinal

voidsetArray（int[]r1,int[]r2,int[]r3,int[]r4）

throwsIllegalArgumentException

{

//

//Ensurethearraysareofequalsize

//

if（r1.length!

=r2.length||r1.length!

=r3.length||r1.length!

=r4.length）

thrownewIllegalArgumentException（"Arraysmustbeofthesamesize"）;

System.arraycopy（r1,0,r3,0,r1.length）;

System.arraycopy（r2,0,r4,0,r1.length）;

}

∙toString方法

无论如何，每一个类都应该定义toString方法：

public

StringtoString（）{

Stringretval="CounterSet:

";

for（inti=0;i

retval+=data.bytes.toString（）;

retval+=data.packets.toString（）;

}

returnretval;

}

}

∙main方法

如果main（String[]）方法已经定义了,那么它应该写在类的底部.

代码编写格式

∙缩进

缩进应缩应用Tab，如果该行过长，可使用换行。

折行后，应比原来的行再缩进一个Tab.

∙{}对

{}中的语句应该单独一行，例如下面的第一行是错误的

if（i>0）{i++};

下面的是正确的

if（i>0）{

i++;

}

∙括号

左括号与右边第一个字符之间不应出现空格，同样的，右括号与左边第一个字符之间也不应出现空格。

if（i==3）错误

if（i==3）正确

∙关系运算符（＝，＝＝，>，<，!

＝，<=，<=）

运算符与两边的字符应空一个格，如：

i=3;错误

i=3;正确

∙逻辑运算符

运算符与两边的字符应空一个格，如：

if（i>=3）&&（i<=10）{

System.out.println（i）;

}

多个参数之间的“，”应紧跟前面的参数，与后面的参数之间空一空格。

如：

publicvoidset（intfirstParam,intsencondParam）{

}

注释规范（CommentDocumentStyle）

注释规范以标准的注释规范为准，在某些地方做了一些简化

如果不太清楚的话，可以先找一个SunMicrosystemsinc.提供的标准代码研究一下，如：

java.lang.Object;javax.swing.JComponent;等，推荐重点研究一下javax.swing.JComponent;类，不只是它的注释的规范，还有它的编码风格和类结构，因为咱们现在要用到的组件基本上都是从这个类继承过来的，了解了它的方法和属性，对它的所有的子类的使用都有帮助

在编码过程中，注意养成较好的编程习惯，如：

先定义好属性和方法，然后添加注释，理一理思路，知道我这个class要做什么，怎么做，对保持思路的连贯性和代码的可读性都会有所帮助

添加好注释后，请使用jbuilder6自带的工具先生成doc文件，看一看这个文件的格式是否和预想中的一样，不一样的话就要修改注释使之一致

（一）注释和嵌入文档

Java里有两种类型的注释。

第一种是传统的、C语言风格的注释，是从C++继承而来的。

这些注释用一个“/*”起头，随后是注释内容，并可跨越多行，最后用一个“*/”结束。

注意许多程序员在连续注释内容的每一行都用一个“*”开头，所以经常能看到象下面这样的内容：

/*这是

*一段注释，

*它跨越了多个行

*/

但请记住，进行编译时，/*和*/之间的所有东西都会被忽略，所以上述注释与下面这段注释并没有什么不同：

/*这是一段注释，

它跨越了多个行*/

第二种类型的注释也起源于C++。

这种注释叫作“单行注释”，以一个“//”起头，表示这一行的所有内容都是注释。

这种类型的注释更常用，因为它书写时更方便。

没有必要在键盘上寻找“/”，再寻找“*”（只需按同样的键两次），而且不必在注释结尾时加一个结束标记。

下面便是这类注释的一个例子：

//这是一条单行注释

1、注释文档

对于Java语言，最体贴的一项设计就是它并没有打算让人们为了写程序而写程序——人们也需要考虑程序的文档化问题。

对于程序的文档化，最大的问题莫过于对文档的维护。

若文档与代码分离，那么每次改变代码后都要改变文档，这无疑会变成相当麻烦的一件事情。

解决的方法看起来似乎很简单：

将代码同文档“链接”起来。

为达到这个目的，最简单的方法是将所有内容都置于同一个文件。

然而，为使一切都整齐划一，还必须使用一种特殊的注释语法，以便标记出特殊的文档；另外还需要一个工具，用于提取这些注释，并按有价值的形式将其展现出来。

这些都是Java必须做到的。

用于提取注释的工具叫作javadoc。

它采用了部分来自Java编译器的技术，查找我们置入程序的特殊注释标记。

它不仅提取由这些标记指示的信息，也将毗邻注释的类名或方法名提取出来。

这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。

javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。

该工具允许我们创建和管理单个源文件，并生动生成有用的文档。

由于有了jvadoc，所以我们能够用标准的方法创建文档。

而且由于它非常方便，所以我们能轻松获得所有Java库的文档。

2、具体语法（Syntax）

所有javadoc命令都只能出现于“/**”注释中。

但和平常一样，注释结束于一个“*/”。

主要通过两种方式来使用javadoc：

嵌入的HTML，或使用“文档标记”。

其中，“文档标记”（Doctags）是一些以“@”开头的命令，置于注释行的起始处（但前导的“*”会被忽略）。

有三种类型的注释文档，它们对应于位于注释后面的元素：

类、变量或者方法。

也就是说，一个类注释正好位于一个类定义之前；变量注释正好位于变量定义之前；而一个方法定义正好位于一个方法定义的前面。

如下面这个简单的例子所示：

/**一个类注释*/

publicclassdocTest{

/**一个变量注释*/

publicinti;

/**一个方法注释*/

publicvoidf（）{}

}

注意javadoc只能为public（公共）和protected（受保护）成员处理注释文档。

“private”（私有）和“友好”（详见5章）成员的注释会被忽略，我们看不到任何输出（也可以用-private标记包括private成员）。

这样做是有道理的，因为只有public和protected成员才可在文件之外使用，这是客户程序员的希望。

然而，所有类注释都会包含到输出结果里。

上述代码的输出是一个HTML文件，它与其他Java文档具有相同的标准格式。

因此，用户会非常熟悉这种格式，可在您设计的类中方便地“漫游”。

设计程序时，请务必考虑输入上述代码，用javadoc处理一下，观看最终HTML文件的效果如何。

3、嵌入HTML（EmbeddedHTML）

javadoc将HTML命令传递给最终生成的HTML文档。

这便使我们能够充分利用HTML的巨大威力。

当然，我们的最终动机是格式化代码，不是为了哗众取宠。

下面列出一个例子：

/**

*

*System.out.println（newDate（））;
*

*/

亦可象在其他Web文档里那样运用HTML，对普通文本进行格式化，使其更具条理、更加美观：

/**

*您甚至可以插入一个列表：

*

*

1. 项目一

   *

2. 项目二

   *

3. 项目三

   *

*/

注意在文档注释中，位于一行最开头的星号会被javadoc丢弃。

同时丢弃的还有前导空格。

javadoc会对所有内容进行格式化，使其与标准的文档外观相符。

不要将

或

---

这样的标题当作嵌入HTML使用，因为javadoc会插入自己的标题，我们给出的标题会与之冲撞。

所有类型的注释文档——类、变量和方法——都支持嵌入HTML。

4@see：

引用其他类（referringtootherclasses）

所有三种类型的注释文档都可包含@see标记，它允许我们引用其他类里的文档。

对于这个标记，javadoc会生成相应的HTML，将其直接链接到其他文档。

格式如下：

@see类名

@see完整类名

@see完整类名#方法名

每一格式都会在生成的文档里自动加入一个超链接的“SeeAlso”（参见）条目。

注意javadoc不会检查我们指定的超链接，不会验证它们是否有效。

5类文档标记（Classdocumentationtags）

随同嵌入HTML和@see引用，类文档还可以包括用于版本信息以及作者姓名的标记。

类文档亦可用于“接口”目的（本书后面会详细解释）。

5.1.@version

格式如下：

@version版本信息

其中，“版本信息”代表任何适合作为版本说明的资料。

若在javadoc命令行使用了“-version”标记，就会从生成的HTML文档里提取出版本信息。

5.2.@author

格式如下：

@author作者信息

其中，“作者信息”包括您的姓名、电子函件地址或者其他任何适宜的资料。

若在javadoc命令行使用了“-author”标记，就会专门从生成的HTML文档里提取出作者信息。

可为一系列作者使用多个这样的标记，但它们必须连续放置。

全部作者信息会一起存入最终HTML代码的单独一个段落里。

6变量文档标记（Variabledocumentationtags）

变量文档只能包括嵌入的HTML以及@see引用。

7方法文档标记（Methoddocumentationtags）

除嵌入HTML和@see引用之外，方法还允许使用针对参数、返回值以及违例的文档标记。

1.@param

格式如下：

@param参数名说明

其中，“参数名”是指参数列表内的标识符，而“说明”代表一些可延续到后续行内的说明文字。

一旦遇到一个新文档标记，就认为前一个说明结束。

可使用任意数量的说明，每个参数一个。

2.@return

格式如下：

@return说明

其中，“说明”是指返回值的含义。

它可延续到后面的行内。

3.@exception

简言之，“违例”（Exception）是一些特殊的对象，若某个方法失败，就可将它们“扔出”对象。

调用一个方法时，尽管只有一个违例对象出现，但一些特殊的方法也许能产生任意数量的、不同类型的违例。

所有这些违例都需要说明。

所以，违例标记的格式如下：

@exception完整类名说明

其中，“完整类名”明确指定了一个违例类的名字，它是在其他某个地方定义好的。

而“说明”（同样可以延续到下面的行）告诉我们为什么这种特殊类型的违例会在方法调用中出现。

4.@deprecated

该标记用于指出一些旧功能已由改进过的新功能取代。

该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。

若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。

8文档示例

//:

c02:

HelloDate.java

//{NoAutomaticTesting}

importjava.util.*;

/**ThefirstThinkinginJavaex