`

java中三种注释及其实际应用的意义

阅读更多

       应用编码规范对于软件本身和软件开发人员而言尤为重要,其中注释就是非常重要的一部分了。你的注释不仅仅可以帮助你理解代码含义,还有利于测试人员测试代码,更加重要的是它在后期生成文档,制作Q&A更是可以节约不少时间和精力。

一、下面我们就讲讲,java中的注释的规范和意义。

一般概念

             1、注释应该增加代码的清晰度
            2
、保持注释的简洁
            3
、在写代码之前或同时写注释
            4
、注释出为什么做了一些事,而不仅仅是做了什么

注释哪些部分

    1Java 文件:必须写明版权信息以及该文件的创建时间和作者;
            2
、类:类的目的、即类所完成的功能,以及该类创建的时间和作者名称;多人一次编辑或修改同一个类时,应在作者名称处出现多人的名称;
            3
、接口: 在满足类注释的基础之上,接口注释应该包含设置接口的目的、它应如何被使用以及如何不被使用。在接口注释清楚的前提下对应的实现类可以不加注释;
            4
、方法注释: 对于设置 (Set 方法 ) 与获取 (Get 方法 ) 成员的方法,在成员变量已有说明的情况下, 可以不加注释;普通成员方法要求说明完成什么功能,参数含义是什么且返回值什么;另外方法的创建时间必须注释清楚,为将来的维护和阅读提供宝贵线索;
            5
、方法内部注释: 控制结构,代码做了些什么以及为什么这样做,处理顺序等,特别是复杂的逻辑处理部分,要尽可能的给出详细的注释;
            6
、参数: 参数含义、及其它任何约束或前提条件;
            7
、属性: 字段描述;
            8
、局部 ( 中间 ) 变量: 无特别意义的情况下不加注释;
        3
、注释格式
            
遵循工程规定的统一注释格式,一般情况下会以 codetemplates.xml 格式的文件导入 IDE(Eclipse)或者用Eclipse默认的;

四、代码格式规范

 

    遵循工程规定的统一代码格式,一般情况下直接使用 IDE(Eclipse) 自带的默认代码格式对代码进行格式化;
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
4
javadoc注释标签语法
@author    
对类的说明 标明开发该类模块的作者
@version   
对类的说明 标明该类模块的版本
@see      
对类、属性、方法的说明 参考转向,也就是相关主题
@param    
对方法的说明 对方法中某参数的说明
@return    
对方法的说明 对方法返回值的说明

@exception  对方法的说明 

 

 五、JAVA注释具体实现

 

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

2、类(模块)注释:
类(模块)注释采用 /** …… */,在每个类(模块)的头部要有必要的注释信息,包括:工程名;类(模块)编号;命名空间;类可以运行的JDK版本;版本号;作者;创建时间;类(模块)功能描述(如功能、主要算法、内部各部分之间的关系、该类与其类的关系等,必要时还要有一些如特别的软硬件要求等说明);主要函数或过程清单及本类(模块)历史修改记录等。
英文注释模版:

/**
* CopyRright (c)2008-xxxx:   <
展望软件Forsoft >                         
* Project:                     <
项目工程名 >                                         
* Module ID:   <(
模块)类编号,可以引用系统设计中的类编号>   
 * Comments:  <
对此类的描述,可以引用系统设计中的描述>        
* JDK version used:      <JDK1.6>                             
* Namespace:           <
命名空间>                             
* Author
        <作者中文名或拼音缩写>                
* Create Date
  <创建日期,格式:YYYY-MM-DD>
* Modified By
   <修改人中文名或拼音缩写>                                        
* Modified Date:  <
修改日期,格式:YYYY-MM-DD>                                   
* Why & What is modified  <
修改原因描述>   
* Version:                  <
版本号>                      
*/
如果模块只进行部分少量代码的修改时,则每次修改须添加以下注释:
//Rewriter
//Rewrite Date
<修改日期:格式YYYY-MM-DD> Start1
/*
原代码内容*/
//End1

将原代码内容注释掉,然后添加新代码使用以下注释:
//Added by
//Add date
<添加日期,格式:YYYY-MM-DD> Start2
//End2

如果模块输入输出参数或功能结构有较大修改,则每次修改必须添加以下
注释:
//Log ID
<Log编号,1开始一次增加>
//Depiction
<对此修改的描述>
//Writer
:修改者中文名
//Rewrite Date
<模块修改日期,格式:YYYY-MM-DD>
3
、接口注释:
接口注释采用 /** …… */,在满足类注释的基础之上,接口注释应该包含描述接口的目的、它应如何被使用以及如何不被使用,块标记部分必须注明作者和版本。在接口注释清楚的前提下对应的实现类可以不加注释。

4、构造函数注释:
构造函数注释采用 /** …… */,描述部分注明构造函数的作用,不一定有块标记部分。
注释模版一:
/**
*
默认构造函数
*/
注释模版二:
/**
* Description :      
带参数构造函数,
*                      
初始化模式名,名称和数据源类型
* @param schema
   模式名
* @param name
   名称
* @param type
数据源类型
*/
5
、函数注释:
函数注释采用 /** ……*/,在每个函数或者过程的前面要有必要的注释信息,包括:函数或过程名称;功能描述;输入、输出及返回值说明;调用关系及被调用关系说明等。函数注释里面可以不出现版本号(@version)。
注释模版一:
/**
  *
:
  *
功能描述:
*
输入参数:     <按照参数定义顺序>
*             <@param
后面空格后跟着参数的变量名字
*           
(不是类型),空格后跟着对该参数的描述。>
*
*
:  - 类型 <说明>
*            <
返回为空(void)的构造函数或者函数,
*            @return
可以省略; 如果返回值就是输入参数,必须

*            用与输入参数的@param相同的描述信息; 必要的时

*            候注明特殊条件写的返回值。>
*
    常:<按照异常名字的字母顺序>
*
:
*
    :
*
:
*
    :
*/
注释模版二:
/**
* FunName:           getFirstSpell
* Description :     
获取汉字拼音首字母的字符串,
*                  
被生成百家姓函数调用
* @param
         str the String是包含汉字的字符串
* @return String
:汉字返回拼音首字母字符串;
*                 
英文字母返回对应的大写字母;
*                
其他非简体汉字返回 '0'
* @Author:       ghc
* @Create Date: 2008-07-02
*/
6
、方法注释:
方法注释采用 /** …… */,对于设置 (Set 方法 ) 与获取 (Get 方法 ) 成员的方法,在成员变量已有说明的情况下,可以不加注释;普通成员方法要求说明完成什么功能,参数含义是什么且返回值什么;另外方法的创建时间必须注释清楚,为将来的维护和阅读提供宝贵线索。
7
、方法内部注释:
控制结构,代码做了些什么以及为什么这样做,处理顺序等,特别是复杂的逻辑处理部分,要尽可能的给出详细的注释。
8
全局变量注释:
要有较详细的注释,包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。
9
、局部(中间)变量注释:
主要变量必须有注释,无特别意义的情况下可以不加注释。
10
、实参/参数注释:
参数含义、及其它任何约束或前提条件。
11
、字段/属性注释: 字段描述,属性说明。
12
、常量:常量通常具有一定的实际意义,要定义相应说明。

 

 

myeclipse的注释相关

1.java文件的自动注释

Window->Preference->Java -> Code Style -> Code Templates

files:新建文件时的注释

Types:类的注视

Field:变量的注释

Constructors:构造函数的注释

methods:一般方法的注释

可以在里edit一些固定的格式或变量 其中user默认取操作系统的名称,可以写死。 日期格式俺想知道怎么改成yyyy-mm-dd

2.JSP文件的注释

Window->Preference-myeclipse-editors-JSP-JSP TEMPLATES

 3.java中用的一些快捷 例:sysout

Window->Preference-java-editor-templates

可以自己写一些参数~例如 user ---zhongjb

 

1
3
分享到:
评论

相关推荐

    java代码注释规范文档

    通过本文档的学习,我们可以了解到Java语言中注释的不同形式及其在实际开发中的应用。良好的注释习惯不仅有助于提升代码的可读性和可维护性,还能够提高团队协作效率。希望每位开发者都能养成良好的注释习惯,让我们...

    jdbc实例+注释 java语言描述

    Java JDBC(Java Database Connectivity)是Java编程语言中用于与数据库交互的一组接口和类,它提供了标准的方法来连接...通过实践和理解这些代码中的注释,你将能够更好地理解JDBC的工作原理及其在实际项目中的应用。

    Java编译工具myeclipse注释模板代码

    在IT行业中,开发效率是至关重要的,而Java作为广泛应用的编程语言,其开发工具的优化配置可以大大提高程序员的生产力。本文将重点介绍“Java编译工具MyEclipse的注释模板代码”及其相关知识点。 首先,MyEclipse是...

    递归与迭代算法及其在JAVA语言中的应用.zip

    在编程世界中,递归和迭代是两种基本的解决问题的方法,尤其在Java语言中,它们在...在阅读“递归与迭代算法及其在JAVA语言中的应用.pdf”这份资料后,相信你将对这两者有更深入的理解,并能灵活地应用到实际项目中。

    删除代码中的注释

    在实际操作中,可以使用正则表达式来实现这两种类型的注释匹配。 3. **处理不同类型的注释**: - **行内注释**:`//`类型的注释通常出现在一行代码的末尾,用于解释该行代码。在处理这类注释时,需要找到每行代码...

    最新Java 基本算法代码示例+注释

    该压缩包中的"suanfa"可能包含一系列的Java源代码文件,每个文件都对应一个或多个基础算法的实现,并且配有详尽的注释,以帮助读者理解每一步的目的和逻辑。下面我们将深入探讨一些常见的Java基础算法及其重要性: ...

    Java语言与JBuilder应用基础模拟题

    根据给定文件的信息,我们可以提炼出一系列关于Java编程语言及其应用的重要知识点,这些知识点涵盖了Java的基本概念、语法特性以及在实际编程中常见的问题和解决方案。 ### 1. Java 文件类型理解 - **Java源文件...

    ssm整合源代码框架,内附注释

    SSM整合是Java Web开发中常见的技术组合,它包含了Spring、Spring MVC和MyBatis三个核心框架。这个压缩包中的源代码提供了一个完整的SSM整合示例,内附注释,便于理解和学习。 首先,Spring作为核心的依赖注入(DI...

    Java语言基础编程.pdf

    Java语言是一种广泛使用的面向对象的编程语言,它以其健壮性、跨平台性和面向对象的特点而闻名。...通过对Java语言基础编程的学习,可以打下坚实的编程基础,为进一步深入学习Java和开发实际应用打下良好的基础。

    基于Java注释(不是注解)生成接口文档的框架与工具,与你的代码没有任何交集,松耦合.zip

    本资源“基于Java注释(不是注解)生成接口文档的框架与工具”提供了一种方法,利用Java源代码中的注释信息自动生成接口文档,这种方法与代码逻辑本身保持松耦合,不会直接修改或影响到实际的业务逻辑。 首先,我们...

    java初学者完整代码+注释 14

    14. **枚举**:了解枚举类型及其在Java中的应用。 这个“day14”文件可能是课程中的第14天内容,可能涵盖了上述某个或多个主题的深入讲解,比如可能会讲解到异常处理的细节,或者集合框架中的某一部分,也可能是多...

    Java应用技术实训任务书

    【Java应用技术实训任务书】是一项针对学生进行的实践性学习任务...这个实训任务不仅锻炼了学生的编程技能,还训练了他们分析问题、设计解决方案、编写文档以及时间管理的能力,是Java教育中非常实际且有益的实践环节。

    代码注释检测工具,用于进行代码注释统计

    在实际应用中,CodeLineNet.exe 的使用流程可能包括以下步骤: 1. 选择要分析的项目或代码库。 2. 运行CodeLineNet.exe 并指定输入目录,包含源代码文件。 3. 工具扫描并分析所有源代码,统计注释数量和位置。 4. ...

    java初学者完整代码+注释 15

    12. **枚举与注解**:了解枚举类型及其在Java中的应用,以及注解的使用场景和自定义注解。 13. **文件与目录操作**:如何创建、删除、重命名文件和目录,以及如何读取和修改文件属性。 14. **JNI(Java Native ...

    java 小程序及其算法实现思路

    Java小程序,通常指的是Java语言编写的小规模应用程序,它们可以独立运行或者嵌入到网页中,为用户提供便捷的功能。本教程的焦点在于通过源码解析,深入理解算法的设计与实现思路,这对于初学者来说是一份非常宝贵的...

    JAVA开发与应用教程

    Java是一种广泛应用的、跨平台的编程语言,以其“一次编写,到处运行”的特性著称。本教程将涵盖Java的基础概念、语法特性、面向对象编程原则以及高级特性和应用。 1. Java基础 - 类与对象:Java是面向对象的语言...

    稀缺资源代码注释器.rar

    本文将详细探讨代码注释器的工作原理、使用方法及其在实际开发中的价值。 首先,我们来理解代码注释器的基本功能。它能够自动解析源代码中的注释部分,将其翻译成易于理解的语言,这对于初学者或非母语编程者来说是...

    spring-framework-5.0.2.RELEASE-中文注释版.zip

    Spring Framework作为Java领域中的核心框架,以其强大的功能和灵活的扩展性深受开发者喜爱。此压缩包"spring-framework-5.0.2.RELEASE-中文注释版.zip"提供了Spring 5.0.2版本的源码,并且附带了详尽的中文注释,...

    Java课件及其源码

    Java,作为一种广泛应用于全球的编程语言,以其面向对象、健壮性、安全性、跨平台等特性,成为初学者和专业人士的首选。这个"Java课件及其源码"资源,是针对高校教学设计的,旨在帮助学生快速掌握Java编程的基础知识...

Global site tag (gtag.js) - Google Analytics