JavaSE - 注释与编程规范

本节学习JavaSE的注释与编程规范。

1. 注释 1.1 注释概述

注释（Comment）是对编写的代码的一种起解释说明的文字，可以让开发人员通过注释更好地理解代码的含义。

Java中的注释类型：

注释可以提高代码的阅读性。写注释是一个程序员必须要具有的良好编程习惯，可以将自己的思想通过注释先整理出来，再用代码去实现。

1.2 单行注释

单行注释的语法格式：

public class Person {
    // 名字
    private String name;
    // 年龄
    private int age;
}

双斜线(/) + 空格 + 注释内容。单行注释如果换行则无效。

1.3 多行注释

多行注释的语法格式：

public class Pet {
    
    private String ownerName;
    
    private String type;
}

斜线和星号()。多行注释允许换行。

1.4 文档注释

文档注释是Java特有的一种注释系统，注释内容可以被JDK提供的工具javadoc.exe所解析，生成一套以网页形式体现的该程序的说明文档。

文档注释的语法格式：

public class Account {
    
    public void withdraw(double money) {
        System.out.println("从账户取出" + money + "元现金。");
    }
}

斜线和双星号()。文档注释一般为多行注释。

文档注释还支持javadoc标签（比如例子中的@author、@param），标签可以更方便地为代码进行解释说明：

标签	作用	使用方式
@author	标识一个类的作者	@author dyj123
@deprecated	指名一个过期的类或成员	@deprecated 高版本已经弃用
{@docRoot}	指明当前文档根目录的路径	{@docRoot}
@exception	标志一个类抛出的异常	@exception exception 异常
{@inheritDoc}	从直接父类继承的注释	{@inheritDoc}
{@link}	插入一个到另一个主题的链接	{@link java.util.Date Date}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	{@linkplain java.util.Date date}
@param	说明一个方法的参数	@param money 现金
@return	说明返回值类型	@return 数量
@see	指定一个到另一个主题的链接	@see java.util.Date
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject和writeExternal方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和@exception标签一样.	@throws exception 异常
{@value}	显示常量的值，该常量必须是static属性。	{@value}
@version	指定类的版本	@version 1.0

使用上面例子的注释来演示javadoc解析，在源码文件所在的位置打开cmd命令行界面，键入以下命令：

javadoc -d accountDoc -authoer -version Account.java

accountDoc为存放生成的说明文档的文件夹，没有则会自动创建文件夹。

生成完成：

打开存放生成的说明文档的文件夹，打开index.html，即可查看生成的说明文档首页：

1.5 注释的一些细节

单行注释与多行注释的内容不参与编译，基于这个特性可以用在其他功能上，比如调试时某些语句发生错误，可以先注释掉它们再排查剩余错误；
多行注释不能嵌套多行注释。多行注释内部可以使用单行注释，虽然没有任何区别；
javadoc工具是将Java源码文件作为输入，输出一些包含程序注释的HTML文件，每一个类的信息将在独自的HTML文件里。javadoc也可以输出继承的树形结构和索引。

2. 编程规范

一个高级程序员必须具备良好的编程习惯，而习惯离不开规范的约束。

Java编码规范总结（腾讯+阿里）- CSDN/pursue_vip