• Java注释规范简介说明


    转自:

    Java注释规范简介说明

    下文笔者讲述java中注释规范的相关说明,如下所示:

    注释形式统一

    在整个团队中,我们应该遵循同一种注释规范,可通过设置注释模板的方式,使用java注释变得规范

    注释的简洁

    通过注释,可直接得到下面代码的功能,为程序后续维护提供便利

    注释的一致性

    在编写代码之前或同步进行代码注释的编写
    修改代码时,也同时修改注释

    注释的位置

    使代码同注释相邻,避免出现代码和注释无法对应,长年累月后都不知道注释所对应的代码

    注释的数量

    整个代码中,注释不宜过多,但也不能太少

    删除无用注释

    删除注释中的临时内容及无用的注释信息,避免后续维护时,给人误导行为

    复杂的注释

    避免编写令人难以理解的注释

    多余的注释

    当有些代码非常清晰时,我们应该避免加入一些无关紧要的注释信息

    必加的注释

    如:一些实现子类中,算法中,我们如果不加入注释,则让后人无法理解相应的代码

    注释不会增加文件的大小

    Java中的注释文件不会增加文件的大小


    java注释示例


    文件头注释

    文件头注释以/*开始,以*/结束,需要注明该文件的创建时间、文件名、命名空间信息
    如:

    /* Created on 2021-11-16
         * File User.java
         * Package com.Java265.other
         * Create Date:2021-11-16
         */
    

    类、接口注释

    类、接口的注释采用/**...*/
    描述部分用来书写该类的作用或者相关信息,块标记部分必须注明作者个版本
    例:

    /** Title:XXXX OCR
         * Description:XXXX OCR 3.0
         * Copyright:Copyright(c) 2021
         * Company:XXXX 有限公司
         * 
         * @author Adeal
         * @version 3.0
         */ 
    

    构造函数注释

    构造函数注释采用/**...*/
    描述部分注明构造函数的作用

     
     /**
         * 默认构造函数
         */
    带块标记的示例如下:
    
    /**
         * 带参数构造函数,初始化模式名、变量名称和数据源类型
         * @param schema
         * Ref 模式名
         * @param name
         * Ref 变量名称
         * @param type
         * by Val 数据源类型
         */
    

    域注释

    域注释可以出现在注释文档里面
    也可以不出现在注释文档里面
    用/**...*/的域注释将会被认为是注释文档而出现在最终生成的HTML报告里面(Javadoc)
    而使用/*...*/的注释则会被忽略掉
    如:

    /**
         * @作者 XXX
         * @创建时间 Jan 16,2021 05:05:11 AM
         */
    

    方法注释

    方法注释采用/**...*/
    描述部分注明方法的功能
    块标记部分注明方法的参数
    返回值,异常信息
    如:

    /**
         * 求最大公约数
         *
         * @param int a
         *  a:待求公约数的参数
         */
  • 相关阅读:
    栈和队列题目练习
    揭秘 Docker 网络:手动实现 Docker 桥接网络
    串口通信(11)-CRC校验介绍&算法
    手撕Vuex-实现actions方法
    Centos7 yum报错 Could not resolve host: mirrorlist.centos.org
    FPGA Zynq MPSOC ZU5EV 下CAN 应用编程
    面试官:group by 有哪些注意事项?
    llama-3 本地化部署实验
    AJAX的Promise(原理)
    代码随想录day48|198. 打家劫舍213. 打家劫舍 II337. 打家劫舍 III
  • 原文地址:https://blog.csdn.net/qq_25073223/article/details/126563977