第4章

大b：“呵呵呵！写得不错，不亏是c大的高材生。”

小a：“师兄你这不是在取笑我嘛！我还有好多问题得请教你哩！”

大b：“行行行……没问题。小师弟好学，师兄哪能袖手旁观呐！对了，你写代码的时候一定要注意代码的规范。”

小a：“代码规范？”

大b：“嗯，来来来，我说给你听。首先是要注意注释文档的格式，注释文档将用来生成html格式的代码报告，所以注释文档必须书写在类、域、构造函数、方法、定义之前。注释文档由两部分组成——描述、块标记。”

例如：

注释

@author大。

@version1.10

publicvoiddoget（httpservletrequestrequest，httpservletresponseresponse）

throwsservletexception，ioexception{

dopost（request，response）；

}

大b：“看！前两行为描述，描述完毕后，由@符号起头为块标记。”

大b：“然后是注释的种类。有文件头注释、构造函数注释、域注释、方法注释和定义注释。”

小a：“什么？注释还有那么多的种类的？我以前都没有用心去记过它的喔。师兄能不能给我讲讲每一种注释的功能和要求啊？”

大b：“这有什么问题哩！举些例子来讲，那样你就容易理解多了。”

小a：“嘿嘿！那感情好。”

大b：“文件头注释已结束，需要注明该文件创建时间，文件名，命名空间信息。”

例如：

描述部分用来书写该类的作用或者相关信息，块标记部分必须注明作者和版本。

如：

classwindowextendsbasewindow{

……

}

大b：“构造函数注释采用描述部分注明构造函数的作用，不一定有块标记部分。域注释可以出现在注释文档里面，也可以不出现在注释文档里面。用的域注释将会被认为是注释文档出现在最终生成的html报告里面，而使用的注释会被忽略。这个应该注意！”

例如：

booleanistrigersuccess=false；

又例如：

booleanistrigersuccess=false；

再例如：

intx=1263732；

大b：“还有就是方法注释，方法注释采用描述部分注明方法的功能，块标记部分注明方法的参数，返回值，异常等信息。定义注释，规则同域注释。”

小a：“喔……原注释还真的是有那么多种类，每个种类都有不同的功能哩！嘿嘿！看来以后我得更认真学习才行哩！”

大b：“呵呵……你能这么想就好喽！对了，小a，注释块标记你知道不？”

小a：“注释块标？嘿嘿！这个……也不知道……”

大b：“没关系，我告诉你。首先是标记的顺序。”

块标记将采用如下顺序：

……

*

*@param（classes，interfaces，methodsandconstructorsonly）

*@return（methodsonly）

*@exception（@throwsisasynonymaddedinjavadoc1.2）

*@author（classesandinterfacesonly，required）

*@version（classesandinterfacesonly，required.seefootnote1）

*@see

*@since

*@serial（@serialdata）

*@deprecated（seehowandwhentodeprecateapis）

*……

一个块标记可以根据需要重复出现多次，多次出现的标记按照如下顺序：

@author按照时间先后顺序（chronological）

@param按照参数定义顺序（declaration）

@throws按照异常名字的字母顺序（alphabetically）

@see按照如下顺序：

@see#field

@see#constructor（type，type……）

@see#constructor（typeid，typeid……）

@see#method（type，type……）

@see#method（typeid，type，id……）

@seeclass

@seeclass#field

@seeclass#constructor（type，type……）

@seeclass#constructor（typeid，typeid）

@seeclass#method（type，type……）

@seeclass#method（typeid，typeid……）

@seepackage.class

@seepackage.class#field

@seepackage.class#constructor（type，type……）

@seepackage.class#constructor（typeid，typeid）

@seepackage.class#method（type，type……）

@seepackage.class#method（typeid，type，id）

@seepackage

小a：“哇噻！块标记还可以按照时间先后顺序，按照参数定义顺序，按照异常名字的字母顺序哩！师兄，你讲得真详细。看来我得好好得花点心思把它们都记下来才好哩！”

大b：“能记住当然好哩！我再给你讲下标记介绍。”

@param标记

@param后面空格后跟着参数的变量名字（不是类型），空格后跟着对该参数的描述。

在描述中第一个名字为该变量的数据类型，表示数据类型的名字前面可以有一个冠词如：a，an，the。如果是int类型的参数则不需要注明数据类型。例如：

……

*@paramchthechar用用来……

*@paramimagetheimage用来……

*@paramnum一个数字……

……

大b：“对于参数的描述如果只是一短语，最好不要首字母大写，结尾也不要句号。对于参数的描述是一个句子，最好不要首字母大写，如果出现了句号这说明你的描述不止一句话。如果非要首字母大写的话，必须用句号来结束句子。（英文的句号）”

公司内部添加byref和byval两个标记，例如：

*@paramimagetheimagebyref用来……

说明该参数是引用传递（指针），byval可以省略，表示是值传递。

大b：“代码规范大概要点就是这些了。听起来好像很多，只要用心，其实也很容易记的。”

小a：“嘿嘿！师兄，你太厉害了！”