4.2　帮助文件范例

在这里是以学校信息代码为例编译生成的本节内容，使用Java Doc（详细内容请参见4.3介绍）进行编译。

[例程4-2]　生成例程4-1的帮助文件。

系统自动生成帮助文件包括版本说明、变量说明、类说明，数组说明等，在这里就以大学信息为例，展现了university类的帮助文件，参见4.2.1节~4.2.5节。

     JavaTeachings.chapter8.src

4.2.1　版本信息

系统自动生成的版本说明如下。

功能简介：是“学籍管理软件”业务逻辑处理程序，主要完成学校数据的维护，其中包括数据查询、数据保存、数据修改、数据删除等。本类是接收collegepage页面的请求。

4.2.2　字段概要

系统自动生成的字段概要内容如下。

大学信息保存，大学信息修改，大学信息查询，大学信息删除。

4.2.3　方法及构造方法摘要

系统自动生成的方法及构造方法摘要如下。

4.2.4　字段详细信息

系统自动生成的字段详细信息如下。

4.2.5　方法或构造方法详细信息

系统自动生成的方法或构造方法详细信息如下。

功能简述：方法体universitySave（）的主要功能是完成学校信息资料的保存，在第14章学习之前。

参数：

     universityCode - String学校代码
     university - String学校名称
     englishTitle - String英文名称
     universityKind - String办学性质
     headUnits - String举办单位
     aim - String办学宗旨
     educationalScope - String办学规模
     managementSystem - String内部管理体制
     fax - char传真
     telephone - char联系电话
     address - char地址
     postcode - char邮编
     URLAddress - String网址

返回：

功能简述：方法体universityUpdate（）的主要功能是完成学校信息资料的修改，在第14章学习之前本方法体作为空方法体存在。

参数：

返回：

     updateStates boolean修改成功或失败

universitySearch

     public java.util.ArrayList universitySearch(java.lang.String universityCode)

功能简述：方法体universitySearch（）的主要功能是完成学校信息资料的查询，在第14章学习之前本方法体作为空方法体存在。

参数：

     universityCode-学校代码。

返回：

     universityList ArrayList学校信息集合

universityDelete

     public boolean universityDelete(java.lang.String universityCode)

功能简述：方法体universityDelete（）的主要功能是完成学校信息资料的删除，在第14章学习之前，本方法体作为空方法体存在。

参数：

     universityCode-学校代码

返回：

     DeleteStates boolean删除成功

4.3　Java编程规范

4.3.1　排版规范

4.3.1.1　排版规则

排版规则主要有以下几条。

（1）程序模块要求采取缩进风格编写，缩进的空格数为4个。

（2）分界符、大括号“{”和“}”应该各占一行并且排在同一列上，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、do、while、switch、case语句中的程序都要采取缩进方式。

[例程4-3]　不符合规范的代码段。

[例程4-4]　符合规范的代码段。

（3）较长的语句、表达式或参数，如果大于70字符，要分成多行书写；长表达式要在低优先级操作符处划分新行，操作符放在新行行首；划分出的新行要缩进，使排版整齐，语句可读。

[例程4-5]　长语句的排版演示。

（4）不允许把多个短语句写在一行中，也就是说一行只允许写一条语句。

[例程4-6]　多个短语句的错误排版。

[例程4-7]　多个短语句的正确排版。

（5）for、do、while、switch和default等语句自占一行，并且if、for、do和while等语句的执行语句无论有多少行，都要加括号{}。

[例程4-8]　判断语句的错误排版。

     if mark<0 System.out.println(＂输入值错误＂);

[例程4-9]　判断语句的正确排版。

（6）相对独立的程序块之间、变量说明之间必须加空行。

[例程4-10]　独立的程序块间的错误排版。

[例程4-11]　独立的程序块间的正确排版。

（7）对齐只使用空格键，不使用Tab键。

（8）两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后加空格。如果是立即操作符，后面不加空格。

[例程4-12]　逗号、分号只在后面加空格。

     String sex,position,school;

4.3.1.2　排版建议

类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。具体格式见例程14-3所示。

[例程4-13]　不交叉放置的排版。

4.3.2　注释规范

程序中的注释是程序设计者与程序阅读者之间通信的重要手段，注释规范对于软件本身和软件开发人员而言尤为重要。在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能地减少软件的维护成本，并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释可以改善软件的可读性，可以让开发人员尽快而彻底地理解源代码；好的注释规范可以最大限度地提高团队开发的合作效率；长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。

4.3.2.1　注释规则

（1）一般情况下，源程序有效注释行必须在30%以上，核心代码复杂性较高的源代码，有效注释行可以是源代码的数倍。

（2）包的注释写入一文件名为package.html的HTML格式说明中并存放于当前路径下。例如，UIW/system/chapter4/src/package.html。

（3）包的注释内容：本包的作用、详细描述本包的内容、产生模块名称和版本、公司版权。如果是导入包，则需要说明包的作用。

包的格式如下。

（4）文件注释：文件注释写入文件头部，包名之前的位置。格式如下：

文件注释内容包括：

（5）类和接口的注释：该注释放在package关键字之后，class或者interface关键字之前。格式如下。

（6）类和接口的注释内容：类的注释主要是功能简单说明等。格式如下。

（7）类属性、公有和保护方法注释写在类属性、公有和保护方法上面。

（8）成员变量的意义、目的、功能注释在可能用到的地方。

（9）公有和保护方法注释内容：列出方法的功能简述、功能描述、输入参数、输出参数、返回值、异常等。格式如下：

（10）对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的异常在注释中说明。

（11）注释应与其描述的代码邻近，对代码的注释应放在其上方或右方。

（12）将注释与其上方的代码用空行隔开。

（13）变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

（14）对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在case语句处理完、进入下一个case语句前明确地注释。

（15）避免在注释中使用缩写，特别是不常用的缩写。

4.3.2.2　注释建议

注释建议有如下几条。

（1）避免在一行代码或表达式中插入注释。

（2）在注释中，使用的语言如果中英文兼有的，建议多使用中文，除非能用非常准确的英文表达和不得不使用。

（3）方法中的单行注释使用//。

（4）顺序实现流程的说明使用顺序号1、2、3、4等，这样明确每个流程执行的顺序。

4.3.3　命名规范

在面向对象编程中，对于类、对象变量、方法等的命名是非常有技巧的，例如，大小写的区分，使用不同字母开头等。但究其本，追其源，在为一个资源命名时，应该本着描述性和唯一性两大特征，才能保证资源之间不冲突，并且便于记忆。

4.3.3.1　命名规则

（1）包的命名。Java包的名字都是由小写单词组成并且这个单词包含其特殊意义，便于编程和维护时阅读。每一名Java程序员都可以编写属于自己的Java包，为了保障每个Java包命名的唯一性，最新的Java编程规范要求程序员在自己定义的包的名称之前加上唯一的前缀。由于互联网上的域名是不会重复的，所以程序员一般采用自己在互联网上的域名作为自己程序包的唯一前缀。

例如：net.frontfree.javagroup。

（2）类的命名。类的名字必须由大写字母开头，一个单词中的其他字母均为小写。如果类名称由多个单词组成，则建议将每个单词的首字母均用大写，如TestPage。如果类名称中包含单词缩写，则建议将这个词的每个字母均用大写，如XMLExample。由于类是设计用来代表对象的，所以建议在命名类时应尽量地选择名词。

（3）接口的命名。接口的命名应该都是名词或形容词，第一个字母都要大写，其他每个单词第一个字母都要大写。要用完整的单词，除非是被公认的单词缩写。例如：

     interface ContainerOwner
     interface Runnable

（4）方法的命名。方法的名字的第一个单词应以小写字母开头，后面的单词则建议用大写字母开头，例如sendMessge（）。

（5）常量的命名。常量的名字应该都使用大写字母，并且指出该常量完整含义。如果一个常量名称由多个单词组成，则建议用下画线来分隔这些单词，例如MAX_VALUE。

（6）参数的命名。参数的命名规范和方法的命名规范相同，而且为了避免阅读程序时造成迷惑，需尽量保证在参数名称为一个单词的情况下，参数的命名尽可能明确特殊含义。

（7）属性名称和方法不能相同，防止出现语言混乱。

（8）全大写的英文描述，英文单词之间用下画线分隔开，并且使用final static修饰。例如：

     public final static score MAX_VALUE=1000;

（9）属性名称可以和公有方法参数相同，不能和局部变量相同。引用非静态成员变量是使用this引用；引用静态成员变量时使用类名引用。

4.3.3.2　命名建议

（1）如果函数名超过15个字母，可以采用去掉元字母的方法或者约定俗成的缩写方式缩写函数名。

（2）准确地确定成员函数的存取控制符号。不是必须使用public属性的，需使用protected；不是必须使用protected属性的，需使用private。

4.3.4　编码规范

4.3.4.1　编码规则

（1）明确方法功能，精确（而不是近似）地实现方法设计。一个函数仅完成一个功能，即使简单功能也应该编写方法实现。

（2）应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责，默认是由方法调用者负责。

说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：一种是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；另一种是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。

（3）明确类的功能，精确（而非近似）地实现类的设计。一个类仅实现一组相近的功能。

（4）所有的数据类必须重载toString（）方法，返回该类有意义的内容。

说明：父类如果实现了比较合理的toString（），子类可以继承，不必再重写。

[例程4-14]　重载String（）方法。

（5）数据库操作、IO操作等需要使用结束close（）的对象必须在try-catch-finally的finally中使用close（）。

[例程4-15]　close（）所处位置。

（6）异常捕获后，如果不对该异常进行处理，则应该记录日志或者ex.printStackTrace（）。

说明：若有特殊原因，必须用注释加以说明。

[例程4-16]　不处理异常时日志记录操作。

（7）自己抛出的异常必须填写详细的描述信息。

说明：便于问题定位。

[例程4-17]　填写异常的描述信息。

     throw new IOException(＂Writing data error!Data:＂+data.toString());

（8）运行期异常使用RuntimeException的子类来表示，不用在可能抛出异常的方法声明上加throws子句。非运行期异常是从Exception继承而来，必须在方法声明上加throws子句。

（9）注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

（10）数组声明的时候使用int[]index，而不要使用int index[]。

（11）调试代码的时候，不要使用System.out和System.err进行打印，应该使用一个包含统一开关的测试类进行统一打印。

4.3.4.2　编码建议

编码建议有以下两条。

（1）一个方法不应抛出太多类型的异常。

说明：如果程序中需要分类处理，则将异常根据分类组织成继承关系。如果确实有很多异常类型，首先考虑用异常描述来区别，throws/exception子句标明的异常最好不要超过3个。

（2）如果多段代码重复做同一件事情，那么在方法的划分上可能存在问题。

说明：若此段代码各语句之间有实质性关联并且是完成同一个功能的，那么可考虑把此段代码构造成一个新的方法。