<<java编程思想>>笔记:注释与嵌入

单行注释

• 以//开头,直到行尾,最常用且最方便的注释方法
• 例子:
  //为该行添加一句注释

多行注释

• 以/*开头,以*/结束,可跨越多行,开头语结束间的所有字符,在编译时都会被忽略
  -例子:

/*这是一只多行注释
可以跨行随意书写
在编译时会被忽略*/

嵌入式文档

• 学名javadoc,多用于对代码的维护,是jdk安装的一部分,javadoc的输出是一个html文档(意味着可以插入html标签),在为类与方法添加可见说明方面发挥重要作用

1. 语法

• 以/**开头,以*/结尾,根据注释类型,分为类、域、方法注释,示例如下:

/** 一只类注释 */
public class test1{
/**一只域注释*/

/**一只方法注释*/
public void function(){}
}

注意:javadoc只能为public与pretetcted成员进行文档注释,对private成员的注释会被自动忽略

• 支持嵌入式html,示例:

/** <a> 
  *System.out.println("一段文字");
<a>
  */

注意:尽量不要添加标题标签,如<h1>,javadoc会插入自己的标题,使用标题标签可能会造成冲突

2. javadoc常用标签

• @see:引用其他类,自动连接到其他类或方法的文档,格式如下:
  @see 包名.类名#方法名
• @author 添加作者姓名,或邮箱地址等信息
• @param 添加参数列表描述
• @return 添加返回值描述
• @version 显示版本号

3.javadoc使用示例

代码结构.png 鼠标放在方法te上,之后点击蓝字.jpg 点击蓝字跳转类注释窗口.png

4.测试代码

/**
 * @see Test1#te  左右互瞧
 * @author zhdpx  这是一个测试类
 */
public class Test1 {

    /**
     * @see Test1  你想瞧一瞧这个类的javadoc吗
     * @param i 这里添加变量说明
     * @param j 传入一个没有软用的String变量
     * @return  这里添加返回值说明
     * @version 1.0 这里添加版本说明 这是一个测试方法
     */
    public int te(int i,String j) {
        int k;
        return i;
    }   
    public static void main(String[] args) {
        Test1 test = new Test1();
        test.te(0, "0");
    }
}

总结

1. 适当的注释可以极大地提高代码可读性,即使是大神,也需要注释才能看得懂许多代码
2. javadoc文档是非常重要的注释文档,能帮助使用者更快捷直接的理解方法或类的使用
3. javadoc还有许多其他标签,请移步
4. 注释以关键简洁为主,写太多会喧宾夺主
5. 轻喷