书写代码注释 --《JAVA编程思想》07

在我们编码的过程中，经常需要对一些特定的代码片段进行注释，否则经过一段时候之后再回顾，很有可能会忘记这段代码所表达的含义，也会对后续修改代码的同事造成理解上的困难。

虽然可以单独写文档来解释代码的含义，但每次修改代码时，会需要在其他的地方额外修改文档，不仅维护成本很高，而且这件事情会令大多数程序员觉得乏味。

所以通常是将代码和文档整合在一起，一般来说使用javadoc风格的注释，javadoc 是 JDK 自带的一部分，无需额外安装，还可导出带注释的javadoc文档（HTML格式），下面我们一起来看看该如何使用。

首先，我们先来了解注释的2种书写方式，分为多行注释和单行注释。

1.多行注释
使用 “/**”表示注释的开头，“*/”表示注释的结尾，在中间书写注释的内容。

    /**
     * 我是一个售票方法
     * 我是一个售票方法
     * 我是一个售票方法
     */
    public int getTicketCount() {
        if (ticketCount < 0) {
            return 0;
        }
        ticketCount--;
        return ticketCount;
    }

2. 单行注释
   使用 “//”开头，在之后书写注释内容，内容不得换行（若一定得换行，可以再书写一个“//”继续表示单行注释）。

    //我是一个售票方法
    public int getTicketCount() {
        if (ticketCount < 0) {
            return 0;
        }
        ticketCount--;
        return ticketCount;
    }

    //我是一个售票方法
    //每次调用余票数减少一
    public int getTicketCount() {
        if (ticketCount < 0) {
            return 0;
        }
        ticketCount--;
        return ticketCount;
    }

我们再来看看常用的javadoc注解：

注解名称	表示含义
@author	代码作者
@version	代码版本
@Date	代码日期
@param	参数名称
@return	返回值含义
@throws	抛出异常类型

下面提供类和方法注释模版，仅供参考

1.类注释模版

/**
 * 这是一个矩形类
 * @author baymax
 * @version 1.0
 * @Date 2021/4/1 20:27
 */
public class Square {

  
}

2.方法注释模版

    /**
     * 计算矩形面积
     * @param width 宽度
     * @param height 高度
     * @return 矩形面积
     * @throws Exception 抛出异常类型
     */
    public int getArea(int width, int height) throws Exception {
        int area = width * height;
        return area;
    }

这里顺带一提JAVA的编码规范，类名一般推荐使用大驼峰命名法(Upper Camel Case)，首字母大写，如果有多个单词拼接而成，后续单词首字母大写，不要用下划线分割；变量名、方法名推荐使用小驼峰命名法（lower Camel Case）首字母大写，如果有多个单词拼接而成，后续单词首字母大写，不要用下划线分割；常量名使用全大写，多个单词用下划线隔开。

类名示例：BaseController、UserUtil
变量名示例：studentName,createTime
方法名示例：getUserName()、importData()
常量名示例：OBJECT_TYPE、ROLE_TYPE

本次分享至此结束，希望本文对你有所帮助，若能点亮下方的点赞按钮，在下感激不尽，谢谢您的【精神支持】。

若有任何疑问，也欢迎与我交流，若存在不足之处，也欢迎各位指正！