代码规范
目 录
1 概述 4
1.1 编程规范的必要性 4
1.2 规范文档的一些要求 4
1.3 如何使代码简洁 4
2 源文件的组织 5
2.1 Java源文件 5
2.1.1 文档开头的注释 5
2.1.2 Package和Import声明 5
2.1.3 类和接口声明 5
3 文档的缩进规则 6
3.1 行的长度 6
3.2 代码行的分割 6
4 代码的注释规则 7
4.1 代码注释的基本原则 8
4.2 注释的运用 8
4.3 Implementation注释的格式 8
4.3.1 块注释 8
4.3.2 单行注释 9
4.3.3 后注释(trailing)(不提倡使用) 9
4.3.4 行尾注释(End-of-line) 9
4.4 文档型注释(Documentation) 10
4.4.1 位置 10
4.4.2 javadoc标签的使用 11
4.4.3 加入样例代码 12
4.4.4 生成javadoc文档 12
5 变量的声明 13
5.1 每行变量声明个数 13
5.2 变量初始化 13
5.3 变量声明的位置 13
5.4 类和接口的声明 14
6 语句 14
6.1 简单语句 14
6.2 复合语句 14
6.3 返回语句 15
6.4 if，if-else，if else-if else语句 15
6.5 for语句 15
6.6 while 循环语句 16
6.7 do-while 语句 16
6.8 switch语句 16
6.9 try-catch 语句 16
7 空行和空格的使用 17
7.1 空行的使用 17
7.2 空格的使用 17
8 命名规范 18
8.1 命名的基本原则 18
8.2 成员函数的命名规则 18
8.2.1 成员访问函数的命名 19
8.3 属性域（fields/property）的命名 19
8.3.1 组件的命名 20
8.4 常量的命名 20
8.5 数组的命名 20
8.6 局部变量的命名标准 20
8.6.1 流（Streams）的命名 20
8.6.2 循环变量的命名 21
8.6.3 异常（Exception）处理中的命名 21
8.6.4 通用对象命名约定 21
8.7 类、接口、包的命名 21
9 编程规范 22
9.1 访问类变量和实例 22
9.2 类变量和方法 22
9.3 常量 22
9.4 变量的声明 23
9.5 几个注意点 23
9.5.1 括号 23
9.5.2 返回值 23
9.5.3 条件运算中的表达式 24
10 编码实例 24
10.1 JAVA源文件的例子 24
11 总结和索引 25
11.1 JAVA命名规范 26
11.2 JAVA文档注释规范 27
11.2.1 基本原则 27
11.2.2 注释的内容 27
11.3 JAVA编码规范 28
12警惕内存泄漏 29
13 J2EE命名规范 30
14 HTML编程规约 33
14.1HTML代码记述规约 33
14.1.1 缩进书写 33
14.1.2．初始设定 33
14.1.3 其他注意事项 33
14.2 HTML命名规约 33
15JavaScript编程规约 34
15.1模块构成 34
15.1.1 HTML 内JavaScript 的记述规则 34
15.1.2 JavaScript 的记述 35
15.1.3 JavaScript 中变量/常量的记述规则 35
15.1.4 函数的记述规则 35
15.1.5 函数的返回值 36
15.1.6 注释 36
15..1.7 外部文件（.js）的记述规则 36
15.2注释规约 36
15.2.1 头部注释 36
15.2.2 变量注释 37
15.2.3 逻辑块注释 37
15.3代码记述规则 38
15.3.1 编程注意事项 38
15.3.2 变量定义 39
15.3.3 Cookie控制 40
15.3.4 命名规约 40
1 概述
编程规范的必要性
代码编程规范之所以重要是因为：
l 软件生命周期中的80%时间是软件维护期；
l 几乎没有任何软件在其整个生命周期中一直由它的原作者来负责维护；
l 代码编程规范能够增加软件的可读性，使得软件工程师更快更准确地理解新代码
l 编程规范能提高软件的封装性；
规范文档的一些要求
后面文中将深入讨论结构良好的程序文档的规则和要求。一个结构良好的文档应首先做到以下几点：
l 文档注释应能增加代码的可读性
编写注释的目的是使你、你的开发伙伴以及后续的开发人员更好地理解你的代码。SUN公司JAVA开发组的Nagle曾说过“如果程序不值得写文档的话，意味着代码也不值得运行”。
l 避免文档的过度修饰
应当注意文档中注释和代码的比例，代码的注释应当简洁、明了。
l 在编码前就开始写文档
原则上讲，我们看一段代码总能发现它在做什么。例如，下面这段代码
中，我们能分析出代码的行为，但不能真正看出它的确切语义。
if ( grandTotal >= 1000.00)
{
grandTotal = grandTotal*0.95;
}
在注释文档中应说明代码所表达的语义和编码设计思想，而不应只是就事论事的讲述代码的行为。
如何使代码简洁
l 为代码写注释文档
l 将代码从逻辑上分段
l 合理的使用空行
l 遵守“30秒规则”，提高代码的可读性
l 书写较短的代码行
2 源文件的组织
一个JAVA源文件是由用空白行和注释分隔开的很多部分组成的，通常文件长度应该小于2000行。
Java源文件
每一个Java源文件都包括一个公共的类或接口。当私有类或接口与公共类相关联的时候，通常可以将其与公共类放在同一个源文件当中。公共类应是文件中的第一个类或接口。
Java源文件的组织结构如下：
l 文件开始的注释段
l Package和Import的声明
l 类和接口声明
2.1.1 文档开头的注释
所有源文件的开始部分都要有一个C语言风格的注释段，列出本程序的类名、版本信息、日期、版权声明。如下所示。
/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/
2.1.2 Package和Import声明
通常Java源文件中第一个非注释行是一个package声明，然后是import声明。如下所示:
package java.awt;
import java.awt.peer.CanvasPeer;
2.1.3 类和接口声明
下表描述了类和接口声明中的一些部分，按照其出现顺序列出：
|
|
类和接口说明 |
说明 |
| 1 |
Class/Interface 文档型注释 |
/** * */ |
| 2 |
Class或Interface声明 |
|
| 3 |
Class或Interface的实现声明 |
该段注释中应该包括任何与类和接口有关的，但又不适于放在文档注释区中的注释说明 |
| 4 |
类静态变量 |
变量出现的顺序为，首先公共变量，然后protected变量，然后是包package一级的变量，然后是私有变量 |
| 5 |
变量实例 |
首先是公共变量，然后protected变量，然后是包package一级的变量，然后是私有变量 |
| 6 |
构造函数（Constructors） |
|
| 7 |
方法 |
方法应该按照功能而不是范围和可访问性来分类。例如，一个私有的类方法可以在两个公共的Instance方法的中间。这样做的目的是提高代码的可读性。 |
3 文档的缩进规则
文档中的缩进基本单位是4个空格。Tab键应当设置为4个空格键。
行的长度
代码行的长度应小于80个字符，否则不能被编辑和处理工具很好的处理。通常文档中代码例子的长度不超过70个字符。
代码行的分割
当一个表达式因太长等原因不适于单行放置的时候，可以根据下面的规则来进行分割：
l 在逗号后面分割；
l 在操作符前分割；
l 应选择高一级的分割而不是低一级的分割；
l 将换行后的表达式的开始部分与前一行的同一级表达式对齐；
l 如果上述规则使得代码难读或代码集中在行的右侧，应4空格的缩进规则；
下面是一些方法调用行分割的例子
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
Type var =
someMethod1(longExpression1,
someMethod2(longExpression2,longExpression3))
以上是好的格式，以下就不是很好。
Type var = someMethod1(longExpression1,
someMethod2(longExpression2,longExpression3))
下面是两个算术表达式的换行分割的例子:
LongName1 =
longName2*( longName3 + longName4 – longName5)
+ 4 * longName6; // 较好的分割方式
LongName1 =
longName2*( longName3 + longName4
– longName5) + 4 * longName6; // 尽量避免这种分割方式
其中，第一方式的较好，因为换行分割点位于括号的外边，同第二种分割相比是分割的级别较高。
当方法中参数很多时，提倡如下的书写：
public void someMethod(Type longExpression1,
Type longExpression2,
Type longExpression3,
Type longExpression4,
Type longExpression5){
...
}
同样，当IF语句或其他循环语句较长时，提倡如下的书写:
if ((condition1 && condition2 )
|| (condition3 && condition4)
|| !(condition5 && condition6)) {
doSomethingAboutIt();
}
下面是3个可接受的表达式的书写方式
alpha = (alongBooleanExpression) ? beta : gamma;
alpha = (alongBooleanExpression) ? beta
: gamma;
alpha = (alongBooleanExpression)
? beta
: gamma;
4 代码的注释规则
JAVA有三种注释方式。如下表所示。
| 注释方式 |
使用场合 |
例 子 |
| 文档型(Document)注 释
|
这种注释放在程序代码中的，接口函数、类、成员函数和域的声明定义之前。 文档型注释由javadoc来处理。如右图所示，为一个类创建一个外部说明文档。 |
/** Customer- A customer is any person or organization that we sell services and products to. @author S.W. Ambler */
|
| C 风格的注释 |
一般来说，用C风格的注释来说明一段代码是不合适的。 这种方式主要用在维护和修改代码时，或者调试中临时关闭一段代码时使用。
|
/* This code was commented out By J.T.Kirk on Dec 9,1997 because it was replaced by the prededing code. Delete it after two years if it is still not applicable.
… … (the source code) */
|
| 单行注释 |
一般在成员函数的内部采用单行注释，主要用来说明事务逻辑（business logic）、代码段、临时变量的声明定义。 |
//Apply a 5% discount to all invoices //over $1000 as defined by the Sarek // generosity compaign started in // Feb. Of 1995 |
代码注释的基本原则
l 注释应能使代码更加明确
l 避免注释部分的过度修饰
l 保持注释部分简单、明确
l 在编码以前就应开始写注释
l 注释应说明设计思路而不是描述代码的行为
注释的运用
JAVA程序有两类注释：一类是实现性注释（implementation comments），另一类是文档型注释（documentation comments）。其中，Implementation 注释有C和C++两种格式，/*...*/ 和//。文档型注释是JAVA程序所独有的，在/**...*/中限定。文档型注释能够被javadoc文件工具提取到HTML文件中。
Implementation注释用于注释代码或者注释特殊的实现。文档型注释主要是描述代码段的说明，从一种非面向实现的角度来写给开发人员阅读读，这些开发人员可能手边并没有源代码。
通常注释应该是给代码一个总的描述或者提供从代码本身不太容易看出的附加性信息。注释的内容应只与读代码和理解代码有关。例如，关于相应的包（package）是如何构建，以及存放在什么目录中，不应该包括在注释中。对代码中不太明显的设计意图进行说明是应该的，但也应避免对一些明显的信息进行重复说明，尽量避免那些随着代码的维护会过时的注释。
注意：
过于频繁的注释常常意味着代码质量较低。但你觉得必须频繁添加注释时，应考虑重写该段代码了。
注释内容不应封在星号（*）或者其它字母围成的矩形框中；注释中不应带有特殊注释字符如制表符（form-feed）和退格符（backspace）。
Implementation注释的格式
JAVA程序段中可以有4种形式的实现注释：块注释（block）、单行注释、后注释（trailing）、行尾注释(end-of-line)。
4.1.1 块注释
块注释用来提供文件、方法、数据结构和算法的描述。块注释主要用在每个文件和方法的开头部分，有时也可用在方法的中间。在一个函数和方法中的块注释应该遵照缩进规则排列到说明对象的同一级深度。
通常块注释前用一个空行和其它的代码段分开。
/*
* Here is a block comment.
*/
另外，用/* - 开始的块注释能够被indent(1)识别出，作为块注释的开始。例如，
/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
*/
注意： 如果你自己不用indent(1),你没有必要用/* -注释开始。
4.1.2 单行注释
单行注释应与其注释的代码处在同一缩进级别中。如果一个注释能写成单行，那么没有必要写成块注释。单行注释前面应有一个空格。例如，
if (condition) {
/* Handle the condition. */
...
}
4.1.3 后注释(trailing)(不提倡使用)
一些非常短的注释可以加在代码的同一行内，但是应该把注释和代码分开足够大的间隔，以增加可读性。如果在一个小代码段中有多个后注释，那么应将其用TAB缩进对齐。
if (a == 2) {
Return TRUE; /* special case */
} else {
return isPrime(a); /*work only for odd a */
}
4.1.4 行尾注释(End-of-line)
“//”注释符能够将整行或部分行注释掉，它不能用在连续的多行文本注释中。它可以用在将小段连续的代码注释掉。所有的3种风格如下所示。
if (foo > 1){
// Do a double-flip
...
}
else{
return false; //Explain why here(不提倡这样使用，应该单独作为一行放在前面)
}
// if (bar > 1) {
//
// // Do a triple-flip.
// ...
//}
//else{
// return false;
//}
文档型注释(Documentation)
JAVA SDK本身提供了较强的代码文档生成功能，只要代码中的注释符合一定的规则就可利用javadoc工具自动生成代码文档。Javadoc 是一种工具，它用于对一组源文件中的声明和文档注释进行语法分析，并生成一组 HTML（HyperText Markup Language，超文本标记语言）页，描述类、内部类、接口、构造函数、方法和域。文档型注释与javadoc紧密相关，可通过灵活运用文档型注释让javadoc自动生成丰富详实的代码文档。Javadoc可从*.java源文件、包说明文件、概述说明文件，以及其它文件中提取信息生成文档。
文档型注释(documentation)主要描述JAVA类、接口、构造器、方法和域。每一个文件注释的内容在/**...*/, 一个类和接口一个注释段。注释应该紧接着类声明的前面。文档型注释的格式是/**及其之后的空格都被javadoc忽略，后续行中的第一个*也被忽略。
/**
* The Example class provides ...
*/
public class Example { ...
注意：
最上一级的类和接口是不缩进的，第一行是(/**)。
其它的成员函数和构造模板要用4空格的缩进。
如果需要对类、接口进行注释但是又不适于采用文档型注释，可以用块注释或者单行注释。例如，一个类的详细实现信息可以通过在类声明后的块注释来做。文档性注释不能放在一个方法和构造之内。
4.1.5 位置
源代码的文档型注释放在任何实体（类、接口、方法、属性、构造函数）的开头。
注意：
1、 只有紧挨着类、接口、方法、属性、构造函数声明的那块注释才被生成javadoc文档，每个声明语句前只有一块注释可被javadoc识别。
2、 函数内部的注释不会生成javadoc文档。
例如下面例子中的注释因为放在了import语句之前，而无法被生成文档：
/** * This is the class comment for the class Whatever. */ import com.sun; // MISTAKE - Important not to put import statement here public class Whatever { }
注释的第一句话
每块文档型注释的第一句话应该是一个概括型语句，可简洁但完整地描述本块注释将要表达的意思。Javadoc将使用该句文字作为成员方法的概述。
注释内部的HTML标签
文档型注释遵循HTML语法规则，可以在注释中插入任何想要的HTML标签以对注释进行格式化。从注释生成的文档中缺省是没有换行的，如需要在最终文档中体现换行，需要在注释中增加换行标签：
/**
* 查询指定条件上的线路配置集。
* 该方法是静态方法，无需实例化一个本类的对象即可调用本方法。
* @param neName 网元的名字
* @param cpn 表明需要查询哪个机框、板、端口上的信息。注意本方法不按机架
* 进行查询，因为一个机架上会有两个网元，所以CPN中的rack设为-1。按从细到粗的
* 顺序，CPN中的其它字段也可设置为-1，表示查询仅精确到上一级单位。
* @return 返回AdslLineConfProfileTable对象组成的Vector。
* */
如需加粗某些文字：
/** * This is a doc comment. * @see java.lang.Object */
javadoc自身的标签
javadoc提供了若干种自定义标签，充分运用这些标签可使生成的文档结构更合理，实用性更强。Javadoc标签以@开头，且是大小写敏感的。包括以下几种标签：@author 、{@docRoot}、@deprecated、@exception、{@link}、@param、@return、@see、@serial、@serialData、@serialField、@since、@throws、@version。下面简要介绍几种很常用且比较重要的标签。
@author name-text
将代码作者的名字生成到文档中。
@param parameter-name description
描述方法的参数
@return description
描述返回值
@see reference
增加一个See Also的链接。
4.1.6 javadoc标签的使用
| 位置 |
标签 |
| 概述文档，一般是overview.html |
@see、{@link}、@since |
| 包文档 |
@see、{@link}、@since、@deprecated |
| 类和接口文档 |
@see、{@link}、@since、@deprecated、@author、@version |
| 属性文档 |
@see、{@link}、@since、@deprecated、@serial、@serialField |
| 构造函数或方法文档 |
@see、{@link}、@since、@deprecated、@param、@return、@throws (@exception)、@serialData |
尽量不要使用括号中的标签，如：@exception；因为在JDK1.2中已经用括号前面的替代了。
4.1.7 加入样例代码
对于较复杂的类或方法，最好在其注释文档中增加一段如何使用本类（方法）的例子代码。由于javadoc生成的文档会忽略空格和换行，应在样例代码段前后加上
标签：/** * A class representing a window on the screen. * For example: * * Window win = new Window(parent); * win.show(); * * * @author Sami Shaio * @version %I%, %G% * @see java.awt.BaseWindow * @see java.awt.Button */class Window extends BaseWindow { ...}
4.1.8 生成javadoc文档
下面给出一个简单的批处理文件用于生成javadoc文档：
del filelist.txt
dir /b /s ..\ems5100\src\*.java > filelist.txt
dir /b /s ..\emsbase\src\*.java >> filelist.txt
javadoc -windowtitle IPMS源程序文档(JavaDOC) -private @filelist.txt
另外，Javadoc 有许多有用的选项，有些相对其他更为常用。下面是实际中我们用来在 Java 平台 API 上运行 javadoc 的命令，它使用了 makefile 变量（除了未列出所有要建文档的包之外）。
javadoc -sourcepath /jdk/src/share/classes \ /* 源文件路径 */
-d /jdk/build/api \ /* 目的目录 */
-use \ /* 添加“用法”文件 */
-splitIndex \ /* 分割索引 A-Z */
-windowtitle $(WINDOWTITLE) \ /* 添加窗口标题 */
-doctitle $(DOCTITLE) \ /* 添加文档标题 */
-header $(HEADER) \ /* 添加运行页眉文本 */
-bottom $(BOTTOM) \ /* 添加底部文本 */
-group $(GROUPCORE) \ /* 概述页的核心标题 */
-group $(GROUPEXT) \ /* 概述页的扩展标题 */
-overview overview-core.html \ /* 概述文本 */
-J-Xmx180m \ /* 180MB 内存 */
java.lang java.lang.reflect \ /* 要建立其文档的包 */
java.util java.io java.net \
java.applet
WINDOWTITLE = 'Java 平台 1.2 最终 API 规范'
DOCTITLE = 'JavaTM Platform 1.2 Final API Specification'
HEADER = 'Java Platform 1.2
Final'
BOTTOM = ' 提交 bug 或功能
Java 是 Sun Microsystems , Inc 在美国和其他国家的商标或注册商标。
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A.保留所有权利。'
GROUPCORE = '"核心包" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT = '"扩展包" "javax.*"'
如果省略 -windowtitle 选项，则 javadoc 将文档标题复制到窗口标题。-windowtitle 选项是没有必要的，除非文档标题包含 HTML 标记。
5 变量的声明
每行变量声明个数
通常JAVA代码中一行只声明一个变量。
int level; // indentation level
int size; // size of table
对比
int level, size;
注意：上面的例子是在变量类型和定义之间用一个空格；实际中也可以用TAB键。例如，
int level; // 缩进层次
int size; // 表的大小
Object currentEntry; // 当前被选的表入口
变量初始化
应在一个变量声明的时就对它进行初始化工作。
变量声明的位置
变量声明只应该放在代码段的开始部分。代码段是指花括号{}所包括的区域。严禁到使用时才声明变量。
Void myMethod() {
int int1 = 0; //beginning of method block
If (condition) {
int int2 = 0; // beginning of “if” block
...
}
}
唯一的例外是for循环中的循环变量，如
for (int i = 0; i < maxLoops; i++){ ... }
为了避免局部变量被高一级的变量所覆盖，应避免在局部代码块中采用同样的变量名称。例如，
int count;
...
myMethod() {
if (condition) {
int count; // 应避免这种情况
...
}
...
}
类和接口的声明
当编写JAVA的类和接口是应该遵循下列格式规则：
l 在方法名称和其后的括号（）之间没有空格;
l 声明类和接口时，表示代码块开始的花括号”{“处在声明的同一行的末尾；
l 花括号”}“应该与相应的花括号”{“所在的行缩进对齐；
l 方法与方法之间用空行隔开；
class Sample extends Object {
int ivar1;
int ivar2;
Sample(int i, int j) {
ivar1 = i;
ivar2 = j;
}
// 空行
int emptyMethod()
};
6 语句
简单语句
每一行应该只包括一个语句，例如：
argv++; //正确
argc++; //正确
argv++; argc--; /错误
复合语句
复合语句是指用一对花括号包围起来的任意数量的简单语句{语句}。
l 括起来的语句应该比复合语句缩进至少一层。
l 开始括号应该在复合语句末尾；结束括号应该在新的一行并且和复合语句括号的开始行对齐。
l 当它们作为控制流程的一部分的时候，应该用括号把所有的复合语句括起来，即使只有一句简单语句，比如if-else或者for语句。这样可以更方便的加入语句而不会引起由于忘掉加括号而引起的偶然性的错误。
返回语句
带值的返回语句不需要用圆括号，除非有时不得不用括号使返回结构更加明显。例如：
return;
return myDisk.size( );
return (size ? size : defaultSize);
if，if-else，if else-if else语句
if-else类语句有如下几种形式：
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
注意：if语句一定要用花括号{}；要避免以下混淆形式：
if (condition) //要避免这种对花括号的忽略！
statement;
for语句
for语句形式如下：
for (initialization; condition; update) {
statements;
}
一个空的for循环语句的形式如下：
for (initianlization; condition; update);
当for循环的initianlization部分和update部分中有多个用逗号隔开的变量时，通常变量的数量不应该超过3个。如果必要的话，可以在for循环的之前（initianlization部分前）或者在循环的尾部（update部分）使用单独的语句来说明。
while 循环语句
一个while语句结构如下：
while (condition) {
statements;
}
下面是一个空的while循环语句：
while (condition);
do-while 语句
一个do-while 循环语句的形式如下：
do {
statements;
} while (condition);
switch语句
一个switch语句的结构如下：
switch (conditon) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
每一个switch语句中应该包括一个default case语句。
try-catch 语句
try-catch语句有以下格式：
try {
statements;
} catch (ExceptionClass e) {
statements;
}
try-catch语句也可以跟随finally，它总是被执行，而不受异常是否抛出的影响。
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
7 空行和空格的使用
空行的使用
用空行将代码段按照逻辑进行分割有助于提高文件的可读性。 空2行的方法应在如下情况中采用：
l 在一个源文件中的各个代码段之间用；
l 在类定义和接口定义之间使用；
空1行的分割方法应该在下列情况中采用：
l 在各个方法之间；
l 在一个方法中的局部变量和它的首次声明之间；
l 在块注释和单行注释之前
l 在一个方法中用空行将代码段从逻辑上划分，以提高文档的可读性
空格的使用
空格应该在下列情况下使用：
l 一个系统保留字和他后面的括号应该用空格分割。例如，
while (true) {
...
}
这样做有助于把系统保留字和方法调用区分开来，因为方法调用与其后的调用参数括号（）之间是没有空格的。
l 在逗号后面用于分隔的多个参数；
l 除了“.”外的所有二元运算符都应用空格与其相应的操作数隔开。空格不能用在一元操作符，如一元加++或一元减-- ，与其相应的操作数之间。例如，
a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
n++;
}
prints(“size is ” + foo + “\n”);
l for 循环表达式应该用空格分开。例如，
for (expr1; expr2; expr3);
l 强制类型转换（cast）后面应该添加空格。例如，
myMethod((byte) aNum, (Object) x);
myMethod((int) (cp + 5), ((int) (i + 3))+ 1);
8 命名规范
命名规范的目的是提高程序的可读性，使程序易于理解。
命名的基本原则
本节的后续部分都将讨论命名规则，这里先提出几项基本命名原则。
l 使用完整的英文描述符准确描述变量variable/域field/类class
较好的命名应该象firstName、grandTotal、CorporateCustomer, 而诸如x1、y1等命名反映任何命名含义，而且造成代码难以理解、维护和改进。
l 采用应用领域相关的术语来命名
如果软件开发人员应注意软件用户的一些约定术语，不应当随意的创造术语。这会降低软件的易用性。
l 采用大小写混合的方式提高命名的可读性
一般情况下应该用小写字母来命名，其中类（class）和接口（interface）名称的首字母用大写。
l 谨慎使用缩写
设计命名中应该慎用缩写命名。如要采用，则应采用统一的缩略规则，并且在文中的相应部分统一采用缩写。例如，采用num作为number的缩写，那么在整个文档中应该始终使用该缩写。
l 避免太长的命名
命名的长度应小于15个字母(但是可以使用更长的形式，以便更好的表达意思)。
l 避免采用仅有大小写不同命名
命名时应避免采用几乎相同的名称。例如，变量名称persistentObject和persistentObjects不应当同时运用；anSqlDatabase和anSQLDatabase也不应同时使用。
l 将标准缩略词的首字母进行大小写变化
有时名称中会含有固定的缩略词，例如SQL代表Standard Query Language. 而在命名时sqlDatabase和SqlDatabase就比sQLDatabase和SQLDatabase易于阅读。
成员函数的命名规则
成员函数名称应采用完整的英文单词组成，除第一个单词外其余的成员单词的首字母用大写。成员函数取名采用动宾结构，名称中的第一个词为动词。例如，
openAccount();
printMailingLabel();
save();
delete();
成员函数的命名应能够准确、简洁地表示其功能。虽然函数名稍微有点长，但还是值得的，因为它能够增加代码的可读性。
8.1.1 成员访问函数的命名
这里主要说明一些对（fields/property）赋值的访问性函数。
Get型函数
Get型函数返回一个域（field）的值。在命名时将“get”作为第一个单词；如果是boolean型的域，那么将“is”作为函数名称的第一个单词。
getFirstName();
getAccountNumber();
getLostEh();
isPersistent();
isAtEnd();
Set型函数
这些函数主要用来对一个域(field)来赋值，命名时将“set”作为第一个单词。
setFirstName(string aName);
setAccountNumber(int anAccountNumber);
setReasonableGoals(Vector newGoals);
setAtEnd(boolean isAtEnd);
| Field |
Type |
Getter name |
Setter name |
| firstName |
String |
GetFirstName() |
setFirstName() |
| address |
SurfaceAddress object |
getAddress() |
setAddress() |
| persistent |
Boolean |
isPersistent() |
setPersittent() |
| customer |
Int |
GetCustomerNumber() |
setCustomerNumber() |
| OrderItems |
Arry of OrderItem Objects |
GetOrderItems() |
setOrderItems() |
如上表所示，象get、set之类的访问控制函数，通常的命名方式是用get/set+“访问对象名”。当对象为布尔型时，用is+“访问对象名”构成，其中对象名称用大小写混合的方式，首字母大写。这些命名约定是JDK标准和JAVA Beans开发时所要求的。
构造函数Constructor
构造函数是成员函数的一种，当一个对象初次创建的时候负责对象初始化工作。构造函数的名称总是与其创建的类完全相同。
Customer();
SavingAccount();
PresistenceBroker();
属性域（fields/property）的命名
通常应该用完整的英文单词来命名一个域，使其名称能够很好的反映其代表的值。
firstName;
zipCode;
unitPrice;
discountRate;
orderItems;
8.1.2 组件的命名
组件接口的命名应该采用全英文单词，后缀为该组件的类型，如botton、list等。命名应能够较好表达该组件的用途，并使得该组件易于在applet或application中查找。组件应避免取诸如botton1、botton2等抽象的名称。
okButton;
customerList;
fileMenu;
newFileMenuItem;
常量的命名
常量的命名常用全英文单词来说明，所有的字母采用大写方式，单词之间用下划线连接。
例如，
MINMUM_BALANCE;
MAX_VALUE;
DEFAULT_START_DATE;
数组的命名
数组（array）和vector的命名方法是，用array和vector所存对象名称的复数表示，名称为全英文单词组成，非开头单词的首字母采用大写。例如，
customers;
orderItems;
aliases;
局部变量的命名标准
局部变量的命名规范与前面提到的field命名原则类似，命名用全英文单词，其中非开头单词的首字母大写。
8.1.3 流（Streams）的命名
当在一个成员函数中打开一个输入输出流的时候，SUN公司的命名约定如下：
l 输入流
命名用in +“流名称”；
l 输出流
命名用out +“流名称”；
l 输入/输出流
命名用inOut +“流名称”;
8.1.4 循环变量的命名
循环变量的命名一般用i、j、k来表示，也可以用更有意义的单词来表示。对于嵌套循环，一般外层循环用i, 第二层用j, 依此类推。
8.1.5 异常（Exception）处理中的命名
异常处理在JAVA代码编程中是十分常用的。通常用小写ex 来作异常对象（exception objection）的对象。例如，
public LocaLize(String FileName) {
try {
filename = FileName;
jbInit();
}
catch(Exception ex) {
ex.printStackTrace();
}
}
8.1.6 通用对象命名约定
下表是SUN公司的一些通用变量和对象的JAVA命名约定。
| 变量类型 |
命名前缀 |
| offset |
Off |
| length |
Len |
| byte |
B |
| char |
C |
| double |
D |
| float |
F |
| long |
L |
| Object |
O |
| String |
S |
| Arbitrary value |
V |
类、接口、包的命名
下表总结了类、接口、包的命名规则。
| 定义类型 |
命名规则 |
例子 |
| Packages |
包名称的前缀总是用小写的ASCII字母来表示的，并且总是采用一级域名，如com,edu,gov,mil.net,ort,或者是ISO 3166标准中规定的国家名的2字母缩写。 一个包名称后面的组件名根据一个组织的各个名称约定来取。
|
com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese com.zte.resmaster.util |
| Class |
类名称应该是名词，且其内部的每一个词的首字母应大写。类名应简单而有意义。组成类名的单词不应用缩写。除非这些缩写已被广泛理解，如URL和HTML。 类名尽量使用名词，或者名词＋动词的形式。 |
Class Raster; Class ImageSprite; |
| Inerfaces |
接口名称的大写规则与类名相同。 接口名尽量使用形容词，如:Runnable。或者名词,并且名词最好是带er,如:RequestHandler。 |
Interface RasterDelegate interface Sroring |
| Methods |
方法的取名应该是动词。它是大小写混合的。成员单词的首字母小写，且中间单词的首字母大写 |
Run(); RunFast(); GetBackground( |
| Variables |
除了变量外，所有的instance,calss,和类常量是大小写混合的。成员单词的首字母小写，且中间单词的首字母大写。另外，变量名称不应该用下划线“_”和“$”符号开始。
变量名称应该简短但有意义。除非是临时使用的变量外，不应当用单个单词来命名变量。
通常临时变量命名时，i，j, k,m,n,来表示整型变量；c,d,e表示字符型变量
|
Int i; Char c; Float myWidth; |
| Constants |
所有的常量名称应该用大写字母表示，各个成员单词之间用下划线“_”相连接。
|
Static final int MIN_WIDTH = 4;
Static final int MAX_WIDTH = 999
Static final int GET_THE_CPU = 1; |
9 编程规范
访问类变量和实例
一般不要随意的将变量和实例的访问属性设置为public。
类变量和方法
不要用一个对象去直接访问类变量或者方法，而是应该用它的类名。例如，
classMethod(); //OK
Aclass.classMethod(); //OK
AnObject.classMethod(); //避免采用
常量
编码中不应直接使用数字常量，除了在for循环中用的-1,0,1等计数常量。
数字常量又叫Magic Sum，有时你自己都不知道它的值究竟是什么。
变量的声明
避免在一条语句中将一个数值赋给多个变量，这样不易阅读。例如，
fooBar.fChar = barFoo.lchar = ‘c’; //应当避免
不要在语句中容易和“相等”混淆的地方放置操作符。例如，
if (c++ = d++) { //JAVA不允许的
...
}
应当改为，
if ((c++ = d++) ！＝ 0) {
...
}
要警惕IF判断语句中的赋值，上面的形式Java编译器拒绝，但是下面的接受：
boolean flag = false;
if (flag = booleanexpression){
...
}
所以，你要清楚你究竟要干什么，不清楚时，写成多行语句。
另外，不要把一个语句嵌入在另外一个语句中。例如，
d = (a = b + c) + r // 避免使用
应该写成,
a = b + c;
d = a + r;
几个注意点
9.1.1 括号
通常建议在有多个操作符的表达式中借助于括号来更加清楚地表达一条语句。这能帮助你和其他程序员更好的理解代码。
if (a == b && c == d) // 避免
if ((a == b) && (c == d)) // 较好
9.1.2 返回值
写代码时应该尽量让你的程序结构很好地体现意图。如，
if (booleanExpression) {
return true;
} else (
return false;
)
应该改为如下语句。
Return booleanExpression;
类似的，
if (condition) {
return x;
}
return y;
应该写为，
return (condition ? x : y);
9.1.3 条件运算中的表达式
如果在三重操作符“?:”中的“?”前面还有二元操作，那么必须采用括号。如，
(x >= 0) ? x : -x;
10 编码实例
JAVA源文件的例子
下面是SUN公司的一段JAVA源文件规范格式的例子。
/*
* @ (#)Blah.java 1.82 99/03/18
*
* Copyright (c) 1999 Sun Microsystems, Inc.
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All Right Reserved.
*
* This software is the confidential and proprietary information of
* Sun Microsystems, Inc. (“Confidential Information”). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Sun
*/
package java.blah;
import java.blah.blahdy.BlahBlah;
/**
* Class description goes here
*
* @ version 1.82 18 Mar 1999
* @ author Fistname Lastname
*/
public class Blsh extends SomeClass {
/* A class implementation comment can go here. */
/** classVar1 documentation comment */
public static int classVar1;
/**
* classVar2 documentation comment that happens to be
* more than one line long
*/
private static Object classVar2;
/** instanceVar1 documentation comment */
public Object instanceVar1;
/** instanceVar2 documentation comment */
protected int instanceVar2;
/** instanceVar3 documentation comment */
private Object[] instanceVar3;
/**
* ...constructor Blah documentation comment ...
*/
public Blash() {
// ...implementation goes here...
}
/**
* ...method doSomething documentation comment...
*/
public void doSomething() {
// ...implementation goes here...
}
/**
* ...method doSomethingElse documentation comment...
* @param someParam description
*/
public void doSomethingElse(Object someParam) {
// ...implementation goes here ...
}
}
11 总结和索引
本节对前面讲述的一些JAVA的研制规范进行总结，主要包括三个方面的内容。
l JAVA命名规范
l JAVA文件规范
l JAVA编码规范
一旦，有任何没有遵守规范的地方应该明确注释出来。
11.1 JAVA命名规范
JAVA命名的总的规则是这样，类和接口名称以及非开头单词的首字母用大写，其它字母用小写。
基本原则：
l 用全英文单词描述
l 采用相应领域的术语来参与命名
l 采用大小写混合的方式提高可读性
l 避免命名长度超过15各字母
l 避免多个命名间十分相似，仅大小写不同
l 避免下划线命名
| 命名项 |
命名规范 |
举例 |
| Arguments/ parameters |
采用全英文描述。为了同变量名称进行区别，可以用“a”和“an”作为前缀 |
customer, account, 或者 aCustomer, anAccount |
| Fields/ properties |
用全英文描述，首字母小写，非开头单词的首字母大写 |
firstName, lastName, warpSpeed |
| 取boolean对象的成员函数 |
用is作名称的前缀 |
isPersistent(), isString, isCharacter(), |
| 类classes |
用全英文描述，所有单词的首字母大写 |
Customer, SavingsAccount |
| 源文件 compilation unit file |
和主class的名称相同 |
Customer.java, SavingsAccount.java, Singleton.java |
| 组件（components/widgets） |
用全英文来描述组件的用途，结尾的单词表示组件的类型 |
OkBotton, CustomerList, fileMenu, |
| 构造函数 constructors |
与类的命名相同 |
Customer(), SavingsAccount() |
| 析构函数 destructors |
一般JAVA没有析构函数，通常在系统的垃圾回收之前，调用finalize()来实现 |
finalize() |
| 异常处理对象 Exceptions |
一般用字母“e”来表示 |
e |
| 常量 |
用大写字母，单词之间用下划线相连 |
MIN_BALANCE, DEFAULT_DATE |
| Get./set 成员函数 |
用get/set作名称的前缀 |
getFirstName(), getWarpSpeed(), setFistName(), setWarpSpeed(), |
| 接口 interfaces |
用全英文描述，所有单词的首字母大写 |
Runnable, Contactable, Prompter, Singleton |
| 包 packages |
用全英文描述，首字母小写，非开头单词的首字母大写 |
java.awt, com.ambysoft.www.persistence.mapping |
| 局部变量 |
用全英文描述，非开头单词的首字母大写。 |
grandTotal, customer, newAccount, |
| 循环变量 |
通常用i, j, k ，也可用其他有意义的单词 |
i, j, k, counter, |
| 成员函数 |
用全英文描述，非开头单词的首字母大写， 命名时采用动宾结构 |
openFile(), addAccount(), |
11.2 JAVA文档注释规范
11.2.1 基本原则
l 注释应能使代码更加明确
l 避免注释部分的过度装饰
l 保持注释部分简单、明确
l 在编码以前就应开始写注释
l 注释应说明设计思路而不是描述代码的行为
11.2.2 注释的内容
下表说明了各个部分注释的主要内容要求。
| 注释项 |
注释的内容 |
| Arguments/parameters |
l 参数的类型 l 如何使用 l 以及使用的限制 l 例子 |
| Fields/properties |
l 可以描述使用的例子; l 一致性问题， l 例子 |
| classes |
l 说明类的用途 l 已经知道的bug l 该类开发和维护的历史记录 |
| Compilation unite |
l 每一个class/interface的定义包括一些简单的描述， l 名字或定义信息 l 版权信息 |
| Interfaces |
l 接口的用途 l 如何使用该接口 |
| 局部变量local variables |
l 变量的用途和目的 |
| 成员函数的文件注释 documentation comments |
l 成员函数的用途和设计目的 l 成员函数的参数说明 l 成员函数返回说明 l 已知道的bug l 成员函数抛出的任何异常 l 访问控制设计 l 代码改变得历史记录 l 成员函数调用的例子 l 应用的前提条件 |
| 成员函数的内部注释 internal comments |
l 结构控制说明 l 代码设计目的 l 局部变量 l 复杂代码的解释 l 处理顺序 |
| 包packages |
l 包的基本原理 l 包中的类（class） |
11.3 JAVA编码规范
有许多规定和标准对提高JAVA代码的可维护性是非常重要的，但其中，如何使你的代码更易于他人的理解是最重要的。
| 代码部分 |
相应的编码规定 |
| 属性（fields） |
l Field应该设为私有 l 不要直接访问属性，应该定义存取成员函数 l 不要用常量静态属性（final static fields）, 应使用存取成员函数 l 不要重名 l 静态属性要初始化 |
| Classes |
l 减少publice和protected 接口的数量 l 在编码之前为类定义公共接口 l 按照如下顺序声明类属性和成员函数 a) constructors b) finalize() c) public member functions d) protected member functions e) private member functions f) private field |
| 局部变量 |
l 不要命名重复 l 每行只能声明一个变量 l 局部变量采用行内注释 l 紧跟在使用之前定义局部变量 |
| 成员函数 |
l 先进行总体说明注释(document comment） l 将代码安逻辑关系分段 l 合理使用空行 l 好的成员函数应能够在30秒钟内被其他人理解 l 写单行的短注释 l 尽可能控制对成员函数内部成员的访问 l 说明操作顺序 |
12 警惕内存泄漏
由于Java中有内存垃圾收集的机制，并且没有指针类型，开发者就可以从C/C++的内存噩梦中解脱出来。正因为如此，很多开发者就不再关注内存的使用问题。小心，这里存在陷阱。
请注意，Java的这个机制是内存垃圾收集而非内存收集！所以，你需要把使用的对象变成JVM可以识别的垃圾。一般而言，在方法中声明使用的变量在方法外面时就会成为垃圾。但是有些却不是，例如：
private HashMap dialogMap = new HashMap();
…
{
JDialog dialog = new JDialog(“XXX”);
…
dialogMap.put(dialog.getTitle(),dialog);
}
…
如果你在整个代码期间都没有调用如下语句：
Object ref =dialogMap.remove(key);
。。。（释放资源，如：((JDialog)ref).dispose()）
ref = null;
或者
dialogMap.clear()（有时，仅仅这个语句还不行）
那么你的代码就存在内存泄漏问题！
几乎所有存储对象的结构都要引起注意，看看是否有资源没有释放，没有成为垃圾而无法回收。下面的对象要严格释放：
java.sql.Connection;
java.sql.Statement;
java.sql.PreparedStatement
java.sql.CallableStatement
java.sql.ResultSet
这些对象如果不释放其资源，不仅仅是内存问题；还将引起数据库问题。如果不释放Connection，那么很快就用尽连接或是数据库巨慢（数据库连接数目还受到Licence的限制）。如果不释放后面的对象资源，那么很快就会用尽数据库游标，因为每打开一次后面的资源就要使用一个游标，即使语句中没有使用游标（其实每个DDL语句都使用一个缺省游标）。而数据库的游标一般是有限制的，Oracle8.1.6中缺省为100，Oracle8.1.7中缺省为300。
千万注意！
可能在一段时间内永远不会碰到内存不足的问题，是不是就不用警惕上面提到的内容呢？
不！
JVM中垃圾内存的收集还受到内存容量的影响。当还有可用内存时，常常不会主动去垃圾收集。这就是为什么常常没有碰到内存不足的问题，因为你机器的内存足够大（256M）。
为了Java程序有序的运行，你可以为它设定一个最大最小内存使用量。就像Weblogic中的一样，如：
-hotspot -ms64m -mx64m。
这样有利于更好的利用垃圾收集机制。
13 J2EE命名规范
在开发J2EE系统的过程中，随着系统开发的深入，如何控制各种对象和资源的命名就成为一个使系统成功的一个重要因素。任何随意性都将导致系统在后期产生混乱，结构不清晰，导致更多的维护成本。
13.1 EJB包结构
实体Bean
Bean ：com.company.projectname.ejbname.ejb.EjbnameEJB
Remote ：com.company.projectname.ejbname.ejb.EjbnameRemote
Home ：com.company.projectname.ejbname.ejb.EjbnameHome
例如：用户对象
Bean : com.zte.resmaster.user.ejb.UserEJB
Remote : com.zte.resmaster.user.ejb.UserRemote
Home : com.zte.resmaster.user.ejb.UserHome
会话Bean
Bean : com.company.project.ejbname.manager.EjbnameEJB
Remote : com.company.project.ejbname.manager.EjbnameRemote
Home : com.company.project.ejbname.manager.EjbnameHome
例如：用户对象
Bean : com.zte.resmaster.user.manager.UserEJB
Remote : com.zte.resmaster.user.manager.UserRemote
Home : com.zte.resmaster.user.manager.UserHome
数据值对象（Data Value设计模式中采用）
com.company.projectname.ejbname.model.EjbnameModel
例如：用户对象
com.zte.resmaster.user.model.UserModel
DAO对象
DAO接口：com.company.projectname.ejbname.dao.EjbnameDAO
DAO实现：com.company.projectname.ejbname.dao.EjbnameDAOImpl
DAO数据库实现：com.company.projectname.ejbname.dao.EjbnameDAODatabase
DAO工厂：com.company.projectname.ejbname.dao.EjbnameDAOFactory
例如：用户对象
DAO接口：com.zte.resmaster.user.dao.UserDAO
DAO实现：com.zte.resmaster.user.dao.UserDAOImpl
DAOOracle实现：com.zte.resmaster.user.dao.UserDAOOracle
DAOSybase实现：com.zte.resmaster.user.dao.UserDAOSybase
DAO工厂：com.zte.resmaster.user.dao.UserDAOFactory
异常
com.company.projectname.ejbname.exceptions.XXXException
例如：用户关键字已经存在的异常
com.zte.resmaster.user.exceptions.UserDupKeyException
工具类
com.company.projectname.ejbname.util.Xxxx
例如：
com.zte.resmaster.user.util.UserEJBHelper
13.2 Servlet包结构
Servlet类
com.company.projectname.subsystem.web.XxxServlet
例如：数据网子系统
com.zte.resmaster.datanet.web.MainServlet
Handler处理类
com.company.projectname.subsystem.web.handlers.ObjectHandler
例如：线路对象
com.zte.resmaster.datanet.web.handlers.LineHandler
Web工具类
com.company.projectname.subsystem.util.XXX
例如：
com.zte.resmaster.datanet.util.DataUtil
Web异常类
com.company.projectname.subsystem.exceptions.XXXException
例如：通用错误类
com.zte.resmaster.datanet.exceptions.GeneralFailureException
13.3 通用工具包结构
数据
com.company.projectname.util.data.XXX
例如：
com.zte.resmaster.util.data.SystemProperties
跟踪调试
com.company.projectname.util.tracer.XXX
例如：
com.zte.resmaster.util.trace.Debug
UI（用户界面）
com.company.projectname.util.ui.XXX
例如：字体选择面板
com.zte.resmaster.util.ui.FontChooserPanel
Theme(界面样式)
com.company.projectname.util.theme.XXX
例如：IzPack的菜单UI样式
com.zte.resmaster.util.theme.IzPackMenuUI
13.4 JNDI名称
EJB注册(可以不用projectname)
projectname.ejbtype.EjbnameEJB
例如：
resmaster.entity.UserEJB
resmaster.session.SecurityEJB
引用EJB
ejb/EjbnameEJB
例如：
ejb/UserEJB
引用数据源(可以使用DatabaseType)
jdbc/DatabaseType/DataSources
例如：jdbc/oracle/ResTxDataSource
14 HTML编程规约
14.1 HTML代码记述规约
14.1.1 缩进书写
要根据HTML 的结构，进行适当的缩进书写，规约如下：
（1）按2 个空格单位缩进；
（2）不要使用TAB 缩进；
（3）
可以不缩进。14.1.2．初始设定
（1）使用
（2） 使用时，必须指定CHECKED。
14.1.3 其他注意事项
（1）标签的记述，使用大写字母；
（2）只在必要的时候使用id，不必要时应删除；
（3）删除不必要的；
（4）使用单引号标注。
【HTML 规范编程例】
| 文本 |
15.1.2 JavaScript 的记述
【JavaScript 记述例】
15.1.3 JavaScript 中变量/常量的记述规则
（1）必须使用var 定义变量；
（2）全局变量：在函数外部定义的变量，HTML 文件内有效。在JavaScript 标签的
开头定义；
（3） 局部变量：在函数内部定义的变量，函数内有效。
15.1.4 函数的记述规则
| 在内记述。 |
15.1.5 函数的返回值
函数有返回值时，使用return 关键字。
15.1.6 注释
（1）行注释
| //注释记述 |
（2）逻辑块注释
| /* 注释记述 */ |
15..1.7 外部文件（.js）的记述规则
（1）外部文件的扩展名为（.js）
（2）HTML 中的外部文件（.js）引用
（3）在外部文件（.js）中定义全局函数
| //函数注释 Function test_sample3（） { 语句 } |
（4）在外部文件（.js）中定义全局变量
| //变量注释 var iOpenForwardOnly; //变量说明 var const lOpenKeyset; //变量说明 var const lOpenDynamic; var const lOpenStatic; |
15.2 注释规约
15.2.1 头部注释
（1）文件注释
因为JavaScript 代码需要从服务器传送到客户端，考虑到对性能的影响，不对文件头
部进行大块的注释说明。
（2）函数注释
和文件注释同样，只对函数头部进行最小限度注释。
| // 生成INTO 语句 Function fncSqlInto(sContainer,lPos) { … … … } |
（3）修改代码的注释
程序修改后，删除不需要的代码，并且在修改行加以简洁明了的说明。
【例】
| //取得变量值 lRowPos = lRowStart; lColPosInit = lColStart; lRowSkipCnt = lRowSkip; lColSkipCnt = lColSkip; // 2010/07/29 删除列跳转处理 lItemStart = lItemStart; lItemEnd = lItemEnd; |
15.2.2 变量注释
（1）每行定义一个变量，并在行后对变量说明；
（2）变量注释应与代码中的注释相同。
【例】
| var sCheckFlg //是否被选择 var lLoopCount //循环变量 |
15.2.3 逻辑块注释
（1）以尽可能小的逻辑块为单位加以注释；
（2）应养成边编程边注释的习惯。编程完成后再注释，很容易和实际代码不符。
【例】
| Function fncImpSujInsAll(lReqCnt, lExeCnt, lCommitFlg) { var sSqlCmd // SQL Command // SQL sSqlCmd = ""; sSqlCmd = sSqlCmd + gfncSqlInsert(TBLID); sSqlCmd = sSqlCmd + gfncSqlColumn(ITEM001, SQL_TOP); sSqlCmd = sSqlCmd + gfncSqlColumn(ITEM002, SQL_OTHER); sSqlCmd = sSqlCmd + gfncSqlValuesToDate(ITEM001, SQL_DATE, SQL_TOP); sSqlCmd = sSqlCmd + gfncSqlValues(ITEM002, SQL_BOTTOM); // 数据插入处理 if (gfncImpSujIns(iReqCnt, tTblRec(), iExeCnt, "", "", sSqlCmd) == false) { // 异常结束时 return false; // 处理结束 } // 返回值 return true; } |
15.3 代码记述规则
15.3.1 编程注意事项
（1）函数定义
·从1 级缩进处开始书写；
·函数内容必须被{ }包括；
·有返回值时，使用「retrun」返回。
【例】
| function gsuImpSujInsAll(lRequestCnt, lExeCnt, lCommitFlg) { … 逻辑 … return true; } |
（2）逻辑记述的注意事项
·以功能为单位函数化编程。注意每个函数不要过大，单个函数原则上不超过100
行；
·以4 个半角空格为单位缩进式书写；
·函数内的定义和逻辑，按4 个半角空格为单位逐层缩进，不要从左端顶头无层次
的书写；
·if 或循环处理逻辑块中，必须按层次缩进；
·语句的最后，使用「；」记述。
【例】
| function TestSample(lShoriNo, sUserId) { var lLoopIndex; // 循环变量 lStatus = True; for (lLoopIndex = 1 ; lLoopIndex <= LOOP_MAX ; lLoopIndex++) { // 处理 Call Test_Sample2; } … // 处理No if (lShoriNo > CHANGE_MAX ) { lShoriNo = 0; } } |
·尽量避免使用对象的缺省属性。但性能上有影响时，特殊情况下允许缺省。
【例】
| ImText1 = "Data1" //不合适 ImText1.Text = "Data1" //推荐 |
·逻辑分支为2 个时，使用if 语句；3 个以上时，使用switch 语句。但复合条件
（&&﹑||等）存在时除外。
·switch 语句块中不需要break 的地方，必须注释说明。
·default 段也必须记述break 语句。
【例】
| switch(IShoriNo) { case 0; IStatus = STS_ERR; /*无break 语句/ case ADD_SYORI; IStatus = STS_ADD; Break; case ADD_UPD; IStatus = STS_UPD; Break; case default; Break; } |
·函数若有返回值时，必须检查返回值。
【例】
| function TestSample (spsSps, sUserId) { … if (CheckUserId(sUserId) == false) { … } … } |
·定义变量﹑类型﹑常量时，尽可能按最小作用域定义。尽可能定义为局部变量。
·1 和0 以外数字尽可能都定义为常量。
15.3.2 变量定义
必须使用var 定义变量。
（1）全局变量
·从JavaScript 的第1 行开始，以意义明确的变量名1 行接1 行地定义；
·以行为单位对变量进行注释。
【例】
| var sCheckFlg //是否被选择 var lLoopCount //循环变量 |
（2）局部变量
·在函数或逻辑块的开头，缩进后开始记述；
·以行为单位对变量进行注释；
·变量需要初始化时，定义的同时进行初始化。
【例】
| function gfncImpSujInsAll(lRequestCnt, lExeCnt, lCommitFlg) { var sFncFlg = “0”; // 调用结束标志位 var lRtn; // 返回值 … lRtn = false; // 异常结束 } |
15.3.3 Cookie控制
JavaScript 只能通过「Cookie 文件」来访问本地文件系统。Cookie 文件的使用规则如
下：
（1）Cookie 文件的限制
·Cookie 文件以行为单位处理
·每个Cookie 文件的最大尺寸4K（4096 字节）
·最大文件数300（其中包含每个独立主域的最大文件数20），超过该限制时，
未使用的文件将被自动删除。
（2）Cookie 文件的读写方法
·数据的读入
【例】
| myData = document.cookie; |
·数据的写入
【例】
| document.cookie = 名称+ 数据+ 期限（GMT） document.cookie =名称+ 数据；expires=期限; （例如： document.cookie = "MZ='721'"） |
15.3.4 命名规约
代码中使用的对象，遵照以下的共通规则进行命名：
（1）根据名称可以推测功能，尽量避免无含义的名称；
（2）单词的开始字母大写，其余部分小写；
（3）和数据库表对应的字段，使用数据库表的字段名；
（4）使用通用的英语单词；
（5）除前缀外避免使用下划线。