磨刀不誤砍材工 - Java的基礎語言要素(注釋-生成你自己的API說明文檔) · 重走J2SE之路

注釋是編程工作中一項重要和必不可少的東西。注釋的使用并不復雜，其之所以如此重要的原因在于什么？來看一個概念解釋：注釋就是對代碼的解釋和說明。目的是為了讓別人和自己很容易看懂。為了讓別人一看就知道這段代碼是做什么用的。正確的程序注釋一般包括序言性注釋和功能性注釋。序言性注釋的主要內容包括模塊的接口、數據的描述和模塊的功能。模塊的功能性注釋的主要內容包括程序段的功能、語句的功能和數據的狀態。所及，總結來說，書寫程序注釋最重要的原因在于：**增強程序的閱讀性**。 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,從而控制循環結束 */ public 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生成自定義的類的說明文檔： ![](https://box.kancloud.cn/2016-08-17_57b4315fb6d35.jpg) 運行完畢后，在你指定的對應目錄下，你會發現多出了一系列html等文件。找到一個名為"index.html"的文件，打開，會發現就如同Java的API說明文檔一樣： ![](https://box.kancloud.cn/2016-08-17_57b4315fd1ad4.jpg) 這樣的說明文檔是大有裨益的，尤其是在如果你向別人提供了一系列的工具類，而別人需要知道使用方法時，這樣的說明文檔就大有作為了。簡單的總結了Java的各種注釋方式，需要我們銘記的是：要成為一名優秀的程序員，良好的書寫代碼注釋是十分重要的。