文档章节

JAVA注释方法及格式

白志华
 白志华
发布于 2015/12/30 14:20
字数 1703
阅读 186
收藏 0

JAVA注释方法及格式

1、单行(single-line)--短注释://……    

单独行注释:在代码中单起一行注释, 注释前最好有一行空行,并与其后的代码具有一样的缩进层级。如果单行无法完成,则应采用块注释。
注释格式:/* 注释内容 */
行头注释:在代码行的开头进行注释。主要为了使该行代码失去意义。
注释格式:// 注释内容
行尾注释:尾端(trailing)--极短的注释,在代码行的行尾进行注释。一般与代码行后空8(至少4)个格,所有注释必须对齐。
注释格式:代码 + 8(至少4)个空格 + // 注释内容

2、块(block)--块注释:/*……*/ 

注释若干行,通常用于提供文件、方法、数据结构等的意义与用途的说明,或者算法的描述。一般位于一个文件或者一个方法的前面,起到引导的作用,也可以根据需要放在合适的位置。这种域注释不会出现在HTML报告中。注释格式通常写成:
/*
  * 注释内容
  */

3、文档注释:/**……*/

        注释若干行,并写入javadoc文档。每个文档注释都会被置于注释定界符/**......*/之中,注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法,以及字段(field)定义之前。注释文档由两部分组成——描述、块标记。注释文档的格式如下: 
/**
* The doGet method of the servlet. 
* This method is called when a form has its tag value method 
* equals to get.
* @param request
*  the request send by the client to the server
* @param response
*  the response send by the server to the client
* @throws ServletException
*  if an error occurred
* @throws IOException
*  if an error occurred
*/

public void doGet (HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
    doPost(request, response);
}

前两行为描述,描述完毕后,由@符号起头为块标记注释。更多有关文档注
释和javadoc的详细资料,参见javadoc的主页: http://java.sun.com/javadoc/index.html

4javadoc注释标签语法

@author    对类的说明 标明开发该类模块的作者 
@version   对类的说明 标明该类模块的版本 
@see      对类、属性、方法的说明 参考转向,也就是相关主题 
@param    对方法的说明 对方法中某参数的说明 
@return    对方法的说明 对方法返回值的说明 
@exception  对方法的说明 对方法可能抛出的异常进行说明

JAVA注释具体实现

1、源文件注释

源文件注释采用 /** …… */,在每个源文件的头部要有必要的注释信息,包括:文件名;文件编号;版本号;作者;创建时间;文件描述包括本文件历史修改记录等。中文注释模版:
/**
文 件 名 
* CopyRright (c) 2008-xxxx:
文件编号:
创 建 人:
    期:
修 改 人:
   期:
   述:
版 本 号:
*/

2、类(模块)注释:

类(模块)注释采用 /** ……*/,在每个类(模块)的头部要有必要的注释信息,包括:工程名;类(模块)编号;命名空间;类可以运行的JDK版本;版本号;作者;创建时间;类(模块)功能描述(如功能、主要算法、内部各部分之间的关系、该类与其类的关系等,必要时还要有一些如特别的软硬件要求等说明);主要函数或过程清单及本类(模块)历史修改记录等。
英文注释模版:
/**
* CopyRright (c)2008-xxxx:                             
* Project:                                                               
* Module ID:       
* Comments:                                             
* JDK version used:                                    
* Namespace:                                         
* Author                         
* Create Date  
* Modified By                                            
* Modified Date:                                      
* Why & What is modified      
* Version:                                         
*/
如果模块只进行部分少量代码的修改时,则每次修改须添加以下注释:
//Rewriter 
//Rewrite Date: Start1: 
/* 原代码内容*/
//End1: 
将原代码内容注释掉,然后添加新代码使用以下注释:
//Added by 
//Add date: Start2: 
//End2
如果模块输入输出参数或功能结构有较大修改,则每次修改必须添加以下
注释:
//Log ID
//Depiction
//Writer:修改者中文名
//Rewrite Date

2.1 接口注释: 

接口注释采用 /** …… */,在满足类注释的基础之上,接口注释应该包含描述接口的目的、它应如何被使用以及如何不被使用,块标记部分必须注明作者和版本。在接口注释清楚的前提下对应的实现类可以不加注释。

3、构造函数注释:

构造函数注释采用 /** …… */,描述部分注明构造函数的作用,不一定有块标记部分。
注释模版一:
/**
默认构造函数
*/
注释模版二:
/**
* Description :       带参数构造函数,
*                       初始化模式名,名称和数据源类型
* @param schema   模式名
* @param name   名称
* @param type: 数据源类型
*/ 

4、函数注释:

函数注释采用 /** ……*/,在每个函数或者过程的前面要有必要的注释信息,包括:函数或过程名称;功能描述;输入、输出及返回值说明;调用关系及被调用关系说明等。函数注释里面可以不出现版本号(@version)。
注释模版一:
/**
  * 函 数 名 :
  * 功能描述:
输入参数:     
*             
*
返 回 值:  - 类型 
*            
    常:
创 建 人
    :
修 改 人:
    :
*/
注释模版二:
/**
* FunName:           getFirstSpell
  * Description :      获取汉字拼音首字母的字符串,
*                   被生成百家姓函数调用
  * @param         str the String是包含汉字的字符串
  * @return String:汉字返回拼音首字母字符串;
*                  英文字母返回对应的大写字母;
*                 其他非简体汉字返回 '0'
* @Author:       ghc
* @Create Date: 2008-07-02
*/ 

5、方法注释: 

方法注释采用 /** …… */,对于设置 (Set 方法 与获取 (Get 方法 )
成员的方法,在成员变量已有说明的情况下,可以不加注释;普通成员方法要求说明完成什么功能,参数含义是什么且返回值什么;另外方法的创建时间必须注释清
楚,为将来的维护和阅读提供宝贵线索。

6、方法内部注释:

控制结构,代码做了些什么以及为什么这样做,处理顺序等,特别是复杂的逻辑处理部分,要尽可能的给出详细的注释。

7全局变量注释:

要有较详细的注释,包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。

8、局部(中间)变量注释: 

主要变量必须有注释,无特别意义的情况下可以不加注释。

9、实参/参数注释: 

参数含义、及其它任何约束或前提条件。


10、字段/属性注释: 字段描述,属性说明。

11、常量:常量通常具有一定的实际意义,要定义相应说明。




© 著作权归作者所有

上一篇: IKAnalyzer分词
白志华
粉丝 34
博文 265
码字总数 57524
作品 0
长沙
程序员
私信 提问
Java8 - lambda 表达式

lambda表达式 为什么需要lambda 表达式 函数对 Java 而言并不重要,在 Java 的世界里,函数无法独立存在。Lambda 表达式为 Java 添加了缺失的函数式编程特点,使我们能将函数当做一等公民看待...

秋风醉了
2018/08/29
130
0
Java 下一代: Groovy、Scala 和 Clojure

在与 Martin Fowler 共同参加的一次主题演讲中,他提供了一个敏锐的观察报告: Java 的遗产是 平台,不是 语言。 最初的 Java 技术工程师曾做过一个了不起的决定,将语言从运行时中分离出来,...

一只死笨死笨的猪
2014/10/23
399
0
Java EE 8的五大新特性详解

版权声明:本文为博主chszs的原创文章,未经博主允许不得转载。 https://blog.csdn.net/chszs/article/details/79802993 Java EE 8的五大新特性详解 2018.4.3 版权声明:本文为博主chszs的原...

chszs
2018/04/03
0
0
使用ConcurrentMap实现高效可靠的原子操作

问题:服务器S1从远程获取多个文件到本地处理。这些文件的数据会被Processor转换成不同类型的数据模型存放至S1的数据库。每个Processor处理逻辑是相互独立的,但是同一个文件的数据可能会被多...

屈想顺
2018/06/14
0
0
扩展 JDT 实现自动代码注释与格式化

简介: 本文介绍了一个为 Eclipse 工作空间中的 Java 代码自动添加统一注释并格式化排版的工具及其具体实现。该工具扩展 Eclipse Java Development Tool(JDT)API,操作 Java 代码。通过本文...

红薯
2010/07/30
1K
1

没有更多内容

加载失败,请刷新页面

加载更多

浅谈Visitor访问者模式

一、前言 什么叫访问,如果大家学过数据结构,对于这点就很清晰了,遍历就是访问的一般形式,单独读取一个元素进行相应的处理也叫作访问,读取到想要查看的内容+对其进行处理就叫作访问,那么...

青衣霓裳
35分钟前
6
0
JS内嵌多个页面,页面之间如何更快捷的查找相关联的页面

假设parent为P页面, P页面有两个子页面,分别为B页面和C页面; B页面和C页面分别内嵌一个iframe,分别为:D页面和E页面 现在通过B页面的内嵌页面D的方法refreshEpage(eUrl)来加载内嵌页面E的内容...

文文1
36分钟前
7
0
Hibernate 5 升级后 getProperties 错误

升级到 Hibernate 5 后,提示有错误: org.hibernate.engine.spi.SessionFactoryImplementor.getProperties()Ljava/util/Map; 完整的错误栈为: java.lang.NoSuchMethodError: org.hibernate......

honeymoose
38分钟前
6
0
mysql-connector-java升级到8.0后保存时间到数据库出现了时差

在一个新项目中用到了新版的mysql jdbc 驱动 <dependency>     <groupId>mysql</groupId>     <artifactId>mysql-connector-java</artifactId>     <version>8.0.18</version> ......

ValSong
41分钟前
7
0
Spring中BeanFactory与FactoryBean的区别

在Spring中有BeanFactory和FactoryBean这2个接口,从名字来看很相似,比较容易搞混。 一、BeanFactory BeanFactory是一个接口,它是Spring中工厂的顶层规范,是SpringIoc容器的核心接口,它定...

大王叫下
43分钟前
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部