精华内容
下载资源
问答
  • 阿里巴巴Java开发手册实战:Java注释规范实例
    2019-08-28 16:37:08

    阿里开发手册:Java注释规范实例

    更多相关内容
  • Java注释规范

    2014-07-11 15:53:34
    定义这个规范的目的是让项目中所有的文档都看起来像一个人写的,增加可读性,减少项目组中因为换人而带来的损失
  • java注释规范

    2012-01-03 15:56:51
    很全的java注释规范,希望给你帮助。谢谢。
  • java注释规范文档

    2011-09-07 13:26:28
    java程序注释规范,每个初学者都应该掌握规范进行编程开发和学习,习惯了规范,自然就会提升代码的质量,提升团队的开发进度!
  • java注释规范.pdf

    2021-10-04 00:07:10
    java注释规范.pdf
  • PAGE / NUMPAGES Java注释文档编写方法 ? 对于Java语言最体贴的一项设计就是它并没有打算让人们为了写程序而写程序人们也需要考虑程序的文档化问题对于程序的文档化最大的问题莫过于对文档的维护若文档与代码分离...
  • 代码要是没有注释,对读者来说就是一堆乱七八糟的字母,为了提高代码的可读性和可维护性,必须对代码进行必要的注释,这里小编整理了一下java注释规范。(一)技巧1:注释当前行快捷方式:ctrl+/2:/* */ 选上要注释的...

    代码要是没有注释,对读者来说就是一堆乱七八糟的字母,为了提高代码的可读性和可维护性,必须对代码进行必要的注释,这里小编整理了一下java注释规范。

    (一)技巧

    1:注释当前行快捷方式:ctrl+/

    2:/* */  选上要注释的代码 ctrl+Shift+/

    (二)在哪些地方加注释?

    1:每个源文件开头都应有一组注释,包含代码的作者,时间;

    2:当编写的代码较长,并且包含了多层嵌套时,花括号会比较多,比较乱,为了方便阅读,应该在某些段落结束的地方加注释,注明该闭合花括号对应的起点;

    3:每个方法都必须加注释,对方法等进行注释时,注释最好放在代码上方,对变量声明进行注释时,注释最好放在行尾,但多行的行尾注释应该对齐;

    4:典型算法必须有注释,代码有bug或不清楚的地方必须加注释,修改过的代码要加修改标志的注释。

    (三)注释遵循哪些原则?

    1:利用缩进和空行将注释与代码分隔开,是代码与注释在没有颜色提示情况下也能很容易分辨出来;

    2:将注释内容与注释分隔符用一个空格隔开,便于查找注释;

    3:对多行注释是尽量不用使用/*  * /,而是用多行“//”,可以避免查找配对的/*  */

    (四)注释方法分类

    1:单行注释-----//

    单独行注释:

    当注释需要单独单用一行时,使用“//” 并在注释前留一个空行,缩进情况要与下面的代码一致。一行放不下时使用多行,此时使用/*  */进行注释。

    行尾注释:

    在代码行的行尾加注释,一般要空8个格,且所有注释必须对齐。

    2:块注释---/*内容*/

    对若干行进行注释,一般放在方法之前,起引导作用,对方法和数据结构等的功能,意义进行说明

    /*

    *注释内容

    */

    3:文档注释

    注释若干行,将会形成HTML格式的代码报告,注释文档必须写在类,成员变量,成员方法,构造方法之前,例如下面是一个servlet创建后生成的一个注释文档

    /**

    * 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();

    }

    4:类注释

    在myEclipse中,可以通过快捷键Alt+Shift+J生成,注释的内容可以通过Eclipse -> Window -> Preferences -> Java -> Code Style -> Code Templates -> Comments ->      Types -> Edt 设置

    格式如下:

    /**

    * @author ASWH

    *

    * @Time 2014-3-30-17:33:01 */

    类的英文注释模板

    /**

    * CopyRright (c)2014-xxxx:

    * Project:

    * Module ID:

    * Comments:

    * JDK version used:

    * Namespace:

    * Author:

    * Create Date:

    * Modified By:

    * Modified Date:

    * Why & What is modified

    * Version:

    */

    中文模板

    /**

    * 文 件 名 :

    * CopyRright (c) 2014-xxxx:

    * 文件编号:

    * 创 建 人:

    * 日 期:

    * 修 改 人:

    * 日 期:

    * 描 述:

    * 版 本 号:

    */

    7:构造函数注释

    /**

    * 构造方法 的描述

    * @param name

    *

    */

    8:方法注释

    /**

    * 生成随机数

    *@param numble

    随机数上限

    *@return

    *@exception (方法有异常的话加)

    * @author ASWH

    * @Time2014-3-30 17:35:29

    */

    9:全局变量注释

    /** The count is the number of charactersin the String. */

    private int count;

    有必要是要说明变量功能,涉及到的方法等等。

    10:普通变量或常量

    //属性

    附录:javadoc参数说明:

    @see 生成文档中的“参见xx 的条目”的超链接,后边可以加上:“类名”、“完整类名”、“完整类名#方法”。可用于:类、方法、变量注释。

    @param 参数的说明。可用于:方法注释。

    @return 返回值的说明。可用于:方法注释。

    @exception 可能抛出异常的说明。可用于:方法注释。

    @version 版本信息。可用于:类注释。

    @author 作者名。可用于:类注释。

    @deprecated 对类或方法的说明 该类或方法不建议使用,引起不推荐使用的警告

    @note  表示注解,暴露给源码阅读者的文档

    @remark 表示评论,暴露给客户程序员的文档

    @since 表示从那个版本起开始有了这个函数

    @see  表示交叉参考

    版权声明:本文为博主原创文章,未经博主允许不得转载。

    展开全文
  • 编码规范(一)----JAVA注释规范

    万次阅读 多人点赞 2017-12-18 12:31:59
    好的代码规范是一个程序员的基本修炼,好的代码注释更能体现一个程序员的思维逻辑,虽然代码是用来给机器运行的,我们只要能写出能让编译器运行的代码就行了,但是如果没有好的编码规范,到项目后期,加入开发的人员...

    一、前言


    好的代码规范是一个程序员的基本修炼,好的代码注释更能体现一个程序员的思维逻辑,虽然代码是用来给机器运行的,我们只要能写出能让编译器运行的代码就行了,但是如果没有好的编码规范,到项目后期,加入开发的人员逐渐增多时,每个人的编码风格都不一样,这就会让项目维护者很难维护,所以开始就要制定一些好的规范来让大家遵守,这样才能写出可维护,健壮的项目,这就是接下来要做的事情。第一节从要从代码注释这一块说起,包含: 版权注释、类注释(Class)、构造函数注释(Constructor)、方法注释(Methods)、代码块注释(Block)、单句注释、字段名注释,然后分别为eclipse、IDEA创建注释模块等。


    二、约定


    下面就是一些常见的注释示例:


    1、版权注释

    版权注释主要用来声明公司的一些基本信息等:

    /** 
     * projectName: xxx
     * fileName: Tk.java 
     * packageName: xxxx
     * date: 2017年12月18日下午12:28:39 
     * copyright(c) 2017-2020 xxx公司
     */


    2、类注释(Class)

    类注释(Class)主要用来声明该类用来做什么,以及创建者、创建日期版本、包名等一些信息:

    /**
     * @version: V1.0
     * @author: fendo
     * @className: user
     * @packageName: user
     * @description: 这是用户类
     * @data: 2017-07-28 12:20
     **/


    3、构造函数注释(Constructor)

    构造函数注释(Constructor)主要用来声明该类的构造函数、入参等信息:

    **
    * @description: 构造函数
    * @param: [sid, pid]
    */  


    4、方法注释(Methods)

    方法注释(Methods)主要用来声明该类的作用、入参、返回值、异常等信息:

    /**
    * @author:  fendo
    * @methodsName: addUser
    * @description: 添加一个用户
    * @param:  xxxx
    * @return: String
    * @throws: 
    */

    5、代码块注释(Block)


    /**
     * 实例化一个用户
     * xxxxxxx
     */
    User user=new User();


    6、单句注释

    User user=new User();  //实例化一个用户

    7、字段名注释

    /**
     * 用户名
     */
    public String name;

    或者使用如下格式:

    /**用户名**/
    public String name;


    三、IDE模板


    接下来就是分别在Eclipse和IDEA中实现上面的注释,然后分别生成模板:


    3.1、Eclipse代码注释


    在Eclipse中可以通过CodeTemplates进行设置,具体步骤如下: Window->Preference->Java->Code Style->Code Template 



    其中有两类一类是Comments、主要是类中的一些通用模板:




    1.文件(Files)注释标签:


    设置版权信息:

    /** 
     * projectName: ${project_name} 
     * fileName: ${file_name} 
     * packageName: ${package_name} 
     * date: ${date}${time} 
     * copyright(c) 2017-2020 xxx公司
     */



    注意: 要打上勾!!


    2.类型(Types)注释标签(类的注释):

    /**   
     * @title: ${file_name} 
     * @package ${package_name} 
     * @description: ${todo}
     * @author: fendo
     * @date: ${date} ${time} 
     * @version: V1.0   
    */



    3.字段(Fields)注释标签:

    /**   
     * @Fields ${field} : ${todo}(用一句话描述这个变量表示什么)   
     */  

    4.构造函数(Constructors)标签:

    /**   
     * @title: ${enclosing_type}   
     * @description: ${todo}(这里用一句话描述这个方法的作用)   
     * @param: ${tags}  
     * @throws:   
     */ 


    5.方法(Methods)标签:

    /**
     *@title: ${enclosing_method} 
     *@description: ${todo}
     *@author: fendo
     *@date: ${date} ${time}
     *${tags}
     *@throws: 
     */ 

    6.覆盖方法(Overriding Methods)标签:

    /**   
     * @title: ${enclosing_method}
     * @description: ${todo}
     * ${tags}   
     * ${see_to_overridden}     
     */ 
    

    7.代表方法(Delegate Methods)标签:

    /**  
     * ${tags}  
     * ${see_to_target}  
     */  

    8.Getter方法标签:

    /**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */  	

    9.Setter方法标签:

    /**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */

    另一类是代码模板如下:



    由于基本的在上面的已经设置好了,所以这里也不需要设置什么,然后就是把这个模板导出来,分发给各开发人员,让他们导进来就行了。




    完整的模板如下:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="gettercomment_context" deleted="false" description="Comment for getter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */  </template><template autoinsert="false" context="constructorcomment_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/**   
     * @title: ${enclosing_type}   
     * @description: ${todo}
     * @param: ${tags}  
     * @throws   
     */ </template><template autoinsert="false" context="filecomment_context" deleted="false" description="Comment for created Java files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment">/** 
     * projectName:${project_name} 
     * fileName:${file_name} 
     * packageName:${package_name} 
     * date:${date}${time} 
     * copyright(c) 2017-2020 xxx公司
     */</template><template autoinsert="false" context="typecomment_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">/**   
     * @title: ${file_name} 
     * @package ${package_name} 
     * @description: ${todo}
     * @author: fendo
     * @date: ${date} ${time} 
     * @version: V1.0   
    */</template><template autoinsert="false" context="methodcomment_context" deleted="false" description="Comment for non-overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment" name="methodcomment">/**
     *@title ${enclosing_method} 
     *@description: ${todo}
     *@author: fendo
     *@date: ${date} ${time}
     *${tags}
     *@throws 
     */ </template><template autoinsert="false" context="overridecomment_context" deleted="false" description="Comment for overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/**   
     * @title: ${enclosing_method}
     * @description: ${todo}
     * ${tags}   
     * ${see_to_overridden}     
     */ </template><template autoinsert="false" context="settercomment_context" deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */</template><template autoinsert="false" context="fieldcomment_context" deleted="false" description="Comment for fields" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/**   
     * @Fields ${field} : ${todo}
     */  </template><template autoinsert="false" context="delegatecomment_context" deleted="false" description="Comment for delegate methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/**  
     * ${tags}  
     * ${see_to_target}  
     */  </template></templates>


    3.2、IDEA代码注释


    idea有两种快捷方式,一个是live templates,一个是file and code templates。


    3.2.1、file and code templates


    IDEA的code templates仅限于类文件头和所有文件头。配置如下图:


    File -- Settings -- Editor -- Code Style -- File and Code Templates
     


     

    模板如下,只能实现类注释,方法注释只能用live templates

    /**   
     * projectName: ${PROJECT_NAME}   
     * fileName: ${NAME}.java  
     * packageName: ${PACKAGE_NAME}   
     * date: ${YEAR}-${MONTH}-${DAY} ${TIME}
     * copyright(c) 2017-2020 xxx公司  
     */  
    #if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
    
    /**  
     * @version: V1.0  
     * @author: fendo  
     * @className: ${NAME}
     * @packageName: ${PACKAGE_NAME}  
     * @description: ${DESCRIPTION}
     * @data: ${YEAR}-${MONTH}-${DAY} ${TIME}
     **/ 
    public class ${NAME} {
    }
    


    3.2.1、live templates


    Live Template用中文应该叫做热加载模板。它的原理就是配置一些常用代码字母缩写,在输入简写时可以出现你预制的模板内容,使得开发效率大大提高。


    在配置当中找到Live Template,右边加号先添加一个TemplateGroup



    选中该分组再点击加号添加一个Live Template.Abbreviation中填写命令,Description填写描述,Template text填写你的配置模板。




    代码注释模板如下:

    /**   
     * @title: $file_name$
     * @package $package_name$
     * @description: 
     * @author: $author$
     * @date: $date$ $time$
     * @version: V1.0   
    */


    注意:

    这里的变量是$$括起来的!!

    然后点击




    选择Everywhere




    然后选择JAVA




    最后点击右下角的Edit variables 按钮,然后弹出一个窗口,如下:  




    注意:

    默认值需要用""括起来!!


    内置函数详细请参考:https://www.jetbrains.com/help/idea/live-template-variables.html


    方法注释如下:

    /**  
     *@title: $enclosing_method$
     *@description: TODO  
     *@author: $author$  
     *@date: $date$ $time$   
     *@param: $param$
     *@return: $return$ 
     *@throws:
     */   



    其中的param也可以使用:

    groovyScript("def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {result+=' * @param ' + params[i] + ((i < params.size() - 1) ? '\\n\\b' : '')}; return result", methodParameters())
    

    这种生成的会换行。


    注意:


    有个很坑的地方就是,使用这个注释的时候,必须在方法内使用,如果在方法外使用有些参数就会获取不到。。。



    不足之处:

    1、live template中的函数方法是读取当前函数体的属性,所以只有在该方法内使用该命令才能获取,如果想获取其他一些信息,如项目名,字段名,根本获取不到,这是个比较鸡肋的地方。
    2、Template variables的Expression不能叠加方法。定制化程度不够好。


    IntelliJ IDEA 的实时代码模板保存在 /templates 目录下,其他系统目录位置如下:

    Windows: C:\Users\xxxx\.IntelliJIdea2017.2\config
    Linux: ~/.<product name><version number>/config/templates
    OS X: ~/Library/Preferences/IdeaIC2017.2/templates



    一些常用的模板:


    1.logger

    private static final Logger logger = LoggerFactory.getLogger($CLASS_NAME$.class);

    2.loggerout

    logger.info("op=start_$METHOD_NAME$, $PARAMS_FORMAT$", $PARAMS$);

    3.test

    @Test
    public void test() {
         
    }


    展开全文
  • java代码注释规范文档

    2018-09-18 10:33:34
    后端开发技术的代码注释规范 单行注释 多行注释 块注释 文档注释 标签注释等等
  • JAVA注释规范

    2012-03-18 17:07:14
    JAVA相关注释规范,如:5、每行注释(连同代码)不要超过120个字(1024×768),最好不要超过80字(800×600) 。
  • Java代码注释规范详解

    2020-09-02 19:50:01
    代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用。下面给大家分享java代码注释规范,需要的朋友参考下
  • JAVA代码注释规范

    2020-10-07 16:27:11
    这里写自定义目录标题JAVA代码注释规范注释原则注释条件:1、基本注释:(必须添加)2、特殊必须加注释:注释格式: JAVA代码注释规范 注释是代码必不可少的一部分,注释提高了代码的可读性;是架起程序设计这与阅读...

    JAVA代码注释规范

    注释是代码必不可少的一部分,注释提高了代码的可读性;是架起程序设计这与阅读者之间的通信桥梁,最大限度的提高了团队开发合作效率,也提高了代码的维护效率。

    注释原则

    1、注释内容:
    简洁明了,含义准确,语言严谨,防止注释多义性!

    注释条件:

    1、基本注释:(必须添加)

    (a):类(接口)的注释

    1.   类(接口)注释
     /**
    
    * 类的描述
    
    * @author Administrator
    
    * @Time 2012-11-2014:49:01
    
    *
    
    */
    
    public class Man extends Person{
    
      ……
    
    }
    

    (b):构造函数的注释

    2.   构造方法注释
    
    例如:
    
    public class Man extends Person {
    
      /**
    
       * 构造方法 的描述
    
       * @param name
    
       *       按钮的上显示的文字
    
       */
    
      public man(String name){
    
         ……
    
      }
    
    }
    

    (c):方法的注释

    3.   方法注释
    
    例如
    
    public class Man extends Person{
    
      /**
    
       * 为按钮添加颜色
    
       *@param color
    
             按钮的颜色
    
    *@return
    
    *@exception  (方法有异常的话加)
    
    * @author Administrator
    
    * @Time2012-11-20 15:02:29
    
       */
    
      public color(String color){
    
         ……
    
      }
    
    }
    

    (d):全局变量的注释

    4.   全局变量注释
    
    例如:
    
    public final class String
    
       implements java.io.Serializable, Comparable<String>,CharSequence
    
    {
    
       /** The value is used for characterstorage. */
    
       private final char value[];
    
       /** The offset is the first index of thestorage that is used. */
    
       private final int offset;
    
       /** The count is the number of charactersin the String. */
    
       private final int count;
    
       /** Cache the hash code for the string */
    
    private int hash; // Default to 0
    
    ……
    
    }
    

    (e):字段/属性的注释

    public class User {
        private String name;//账号
        private String password;//密码
    
        private int nums;//会员号
    
    

    注:简单的代码做简单的注释,只是内容一般控制在10个字内;持久化对象或vo对象的getter、setter方法不需要注释!

    2、特殊必须加注释:

    (a) 典型算法必须有注释。

    (b) 在代码不明晰处必须有注释。

    © 在代码修改处加上修改标识的注释。

    (d) 在循环和逻辑分支组成的代码中加注释。

    (e) 为他人提供的接口必须加详细注释。
    具体的注释格式自行定义

    注释格式:

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

    2、块(block)注释:“/……/”

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

    4、javadoc 注释标签语法

    标签作用域说明
    @author标明开发该类模块的作者
    @version标明该类模块的版本
    @see类,属性,方法参考转向(相关主题)
    @param方法对方法中某参数的说明
    @return方法对方法返回值的说明
    @exception方法方法抛出的异常类型
    @throws方法方法抛出的异常类型说明
    @deprecated方法说明不建议使用该方法
    展开全文
  • Java注释规范整理

    千次阅读 2014-07-19 15:20:56
    在软件开发的过程中总是强调注释的规范,但是没有一个具体的标准进行说明,通常都是在... JAVA注释规范 版本/状态 作者 版本日期 1.0 ghc 2008-07-02 一、背景 1、当我们第一次接触某段代码,但又被要求在极短的时
  • Java注释规范整理.pdf

    2012-12-19 10:51:46
    但是没有一个具体的标准进行说明,通常都是在代码编写规范中简单的描述几句,不能作为一个代码注释检查的标准和依据,做什么都要有一个依据吗:),现在我特整理了一个《Java注释规范》,内容来自网络、书籍和自己的...
  • Java标准注释规范

    2021-03-05 11:53:32
    JAVA注释技巧1、空行和空白字符也是一种特殊注释。利用缩进和空行,使代码与注释容易区别,并协调美观。2、当代码比较长,特别是有多重嵌套时,为了使层次清晰,应当在一些段落的结束处加注释(在闭合的右花括号后...
  • 代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。下面通过本文说一下我们在日常开发中使用的代码注释规范
  • JAVA代码注释规范codetemplates.xml,可直接导入Eclipse,代码注释效果很棒!
  • Java 注释规范详解

    千次阅读 2015-04-01 22:36:09
    Java 的编写过程中我们需要对一些程序进行注释,除了自己方便阅读,更为别人更好理解自己的程序,所以我们需要进行一些注释,可以是编程思路或者是程序的作用,总而言之就是方便自己他人更好的阅读。
  • java的命名规范与注释规范

    千次阅读 多人点赞 2018-07-17 20:10:19
    一、java命名规范 1、项目名全部小写 2、包名全部小写 3、类名首字母大写,若类名由多个单词构成,每个单词首字母大写,即大驼峰命名 public class HelloWorld(){ } 4、变量名、方法名首字母小写,若其由多个...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 125,621
精华内容 50,248
关键字:

java 注释规范

java 订阅
友情链接: upload.rar