java的基本語言元素--註釋

註釋是編程工作中一項重要和必不可少的東西。註釋的使用並不複雜，其之所以如此重要的原因在於什麼？

來看一個概念解釋：註釋就是對代碼的解釋和說明。目的是爲了讓別人和自己很容易看懂。爲了讓別人一看就知道這段代碼是做什麼用的。

正確的程序註釋一般包括序言性註釋和功能性註釋。序言性註釋的主要內容包括模塊的接口、數據的描述和模塊的功能。

模塊的功能性註釋的主要內容包括程序段的功能、語句的功能和數據的狀態。

所及，總結來說，書寫程序註釋最重要的原因在於：增強程序的閱讀性。

Java中提供了三種註釋方式：

• 單行註釋：//這是我的單行註釋

• 多行註釋：/*

                *這是我的多行註釋

                */

• 文檔註釋：/**

                *

                */

讓我們分別通過一些簡單的實際運用來了解一下其使用方式：

1.單行註釋的應用(單行註釋基本也是我們在實際開發中最頻繁使用的註釋方式)。

我們可以通過對同一個程序，不加註釋與加上註釋的兩種方式來形象的瞭解註釋帶來的好處。

不加註釋的方式：

package com.tsr.j2seoverstudy.base;

public class JavaExpDemo {
    private boolean flag = true;

    public void myLoop() {
        int num = 0;
        while (flag) {
            System.out.println(++num);
            if (num >= 10) {
                flag = false;
            }
        }
    }
}

加上註釋的方式：

package com.tsr.j2seoverstudy.base;

public class JavaExpDemo {
    private boolean flag = true; // 這是我定義的循環控制標記

    public void myLoop() {
        int num = 0;         //這是我定義的作爲循環控制的數
        while (flag) {
            System.out.println(++num); //循環控制數自增運算並輸出自增後的值
            if (num >= 10) {           //當控制數自增到大於等於10時
                flag = false;      //改變循環控制標記，結束循環
            }
        }
    }
}

其程序閱讀性的強弱不言而喻。

二、多行註釋的應用

Java中多行註釋的定義格式爲："/* */"的形式。顧名思義，多行註釋對應於單行註釋，通常就是當我們所需說明的註釋較長，這時再使用單行註釋就會顯的不美觀，並且麻煩，因爲可能你需要書寫多次"//".於是就有了多行註釋的用武之地。

同樣以我們上面使用單行註釋的相同代碼來說，如果我們想要對myLoop方法的功能進行註釋說明，就可以使用多行註釋：

      /*
* 自定義的循環控制
* 功能說明：
* 通過循環標記flag對循環進行控制，當flag值爲true時，將繼續循環
* 同時定義了一個初始值爲0的int型變量num,每次循環num會進行自增運算
* 當num自增到大於等於0時，循環標記flag的值將被修改爲false,從而控制循環結束
*/
ublic void myLoop() {
int num = 0;             //這是我定義的作爲循環控制的數
while (flag) {
    System.out.println(++num); //循環控制數自增運算並輸出自增後的值
    if (num >= 10) {           //當控制數自增到大於等於10時
        flag = false;          //改變循環控制標記，結束循環
    }
}

三、文檔註釋的應用

這是我覺得很酷的一種註釋方式。爲什麼這樣說呢？

作爲一名Java語言的使用者，我們都經常和一個東西打交道：那就是Java的API說明文檔。

通過文檔註釋，我們也可以對自己定義的類，生成一份“說明書”，也就所謂的API說明文檔。

來看一下，首先我們定義一個自己的工具類：

package com.tsr.j2seoverstudy.base;

/**
 * 我的數學工具類,提供一系列相應的數學相關運算方法..
 * @author Hql
 * @version 1.0
 */
public class MyMathUtil {
    /**
     * 比較獲取兩個數中的最小數
     * @param num1
     * @param num2
     * @return 最小數
     */
    public static int min(int num1, int num2) {
        return num1 > num2 ? num2 : num1;
    }

    /**
     * 比較獲取兩個數中的最大數
     * @param num1
     * @param num2
     * @return 最大數
     */
    public static int max(int num1, int num2) {
        return num1 > num2 ? num1 : num2;
    }
}

我們對我們提供的類以及方法等加上了文檔註釋。

這時，正如我們可以通過Java提供的javac.exe工具對自己的類進行編譯一樣，我們可以通過另一樣工具javadoc.exe生成自定義的類的說明文檔：

運行完畢後，在你指定的對應目錄下，你會發現多出了一系列html等文件。

找到一個名爲"index.html"的文件，打開，會發現就如同Java的API說明文檔一樣：

這樣的說明文檔是大有裨益的，尤其是在如果你向別人提供了一系列的工具類，而別人需要知道使用方法時，這樣的說明文檔就大有作爲了。

簡單的總結了Java的各種註釋方式，需要我們銘記的是：

要成爲一名優秀的程序員，良好的書寫代碼註釋是十分重要的。