一、開篇

在程序開發(fā)過程中，經(jīng)常會(huì)遇到修改其他人代碼的情況。這時(shí)候手里的代碼會(huì)有這么幾種情況：

有條理，通俗易懂；

沒有條理，通俗易懂；

有條理，高深；

沒有條理，高深。

一般說來，遇到前兩種的比較幸運(yùn)，至少通過瀏覽一遍代碼，就能知道需要修改哪些地方，如何修改。但遇到后兩種情況，尤其第4種情況，絕對(duì)是云里霧里，極有可能自己重新寫了。

這就出現(xiàn)了幾個(gè)問題：

如何高質(zhì)量的進(jìn)行開發(fā)和維護(hù)工作；

如何在第一次接觸代碼時(shí)迅速了解這段代碼的意圖及功能；

如何避免冗余或雜亂不堪的代碼。

程序中的注釋是軟件設(shè)計(jì)者/軟件開發(fā)人員與程序閱讀者之間通信的重要手段，良好的規(guī)范及良好的執(zhí)行規(guī)范對(duì)于軟件本身和軟件開發(fā)人員尤為重要。在軟件的生命周期中，良好的注釋可以改善代碼的可讀性，能夠使開發(fā)人員盡快理解前輩遺留的代碼(其中不乏使用了巧妙的可讀性差的算法)；再者，能夠最大限度的規(guī)范代碼，提高團(tuán)隊(duì)合作效率；其次，長(zhǎng)期遵循編碼規(guī)范，能夠養(yǎng)成開發(fā)人員良好的編碼習(xí)慣及更加嚴(yán)謹(jǐn)?shù)乃季S；并且，在敏捷開發(fā)思想中甚至提出將注釋轉(zhuǎn)為代碼的概念。

二、Java注釋方法及格式

1、單行注釋(或短注釋)：// ...

單行注釋起源于C++，以一個(gè)“//”起頭，表示這一行的所有內(nèi)容都是注釋。這種類型的注釋更常用，因?yàn)樗鼤鴮憰r(shí)更方便。沒有必要在鍵盤上尋找“/”，再尋找“*”（只需按同樣的鍵兩次），而且不必在注釋結(jié)尾時(shí)加一個(gè)結(jié)束標(biāo)記。下面便是這類注釋的一個(gè)例子：

// 這是一條單行注釋

2、塊注釋：/* ... */

這種注釋是傳統(tǒng)的C語(yǔ)言風(fēng)格的注釋，以一個(gè)“/*”起頭，隨后是注釋內(nèi)容，并可跨越多行，最后用一個(gè)“*/”結(jié)束。這種注釋可以注釋若干行，通常用于提供文件、方法、數(shù)據(jù)結(jié)構(gòu)等的意義與用途的說明，或者算法的描述。一般位于一個(gè)文件或者一個(gè)方法的前面，起到引導(dǎo)的作用，也可以根據(jù)需要放在合適的位置。許多程序員在連續(xù)注釋內(nèi)容的每一行都用一個(gè)“*”開頭，所以經(jīng)常能看到象下面這樣的內(nèi)容：

/*

* 這里是

* 注釋內(nèi)容，

* 跨越多行。

*/

注：塊注釋不會(huì)出現(xiàn)在HTML文檔中。所以下面的注釋和上面的沒有區(qū)別：

/* 這里是注釋內(nèi)容，

跨越多行。*/

3、文檔注釋：/** ... */

/**

* 注釋內(nèi)容

*/

在軟件開發(fā)過程中，除了編寫程序之外，還應(yīng)該實(shí)現(xiàn)程序的文檔化。對(duì)于程序的文檔化，最大的問題莫過于對(duì)文檔的維護(hù)。若文檔與代碼分離，那么每次修改代碼后都要改變文檔，對(duì)于大多數(shù)開發(fā)人員都是相當(dāng)麻煩的事（好不容易修改好了代碼，誰(shuí)還有閑心再找到文檔并修改文檔）。最簡(jiǎn)單的解決辦法就是將文檔與代碼“鏈接”起來。在Java中，很貼心的設(shè)計(jì)了將代碼與文檔放置在同一個(gè)文件。同時(shí)，為了讓文檔與代碼整齊劃一，增加了特殊的注釋語(yǔ)法，用于標(biāo)記特殊的文檔；為了提取注釋并以有意義的方式展現(xiàn)，增加了一個(gè)工具（小伙伴們一定都知道說的是javac）。

文檔注釋必須寫在/** ... */中，使用嵌入的HTML或文檔標(biāo)記兩種方式使用javac。有三種類型的注釋文檔，它們對(duì)應(yīng)于位于注釋后面的元素：類、變量或者方法。也就是說，一個(gè)類注釋正好位于一個(gè)類定義之前；變量注釋正好位于變量定義之前；一個(gè)方法定義正好位于一個(gè)方法定義的之前。而且，在默認(rèn)情況下，javac只能為public和protected成員處理文檔注釋，忽略private成員的注釋（可以通過-private標(biāo)記包含private成員）。

可以像繪制HTML頁(yè)面一樣編寫文檔，因?yàn)閖avac最終生成HTML頁(yè)面，所以只要是正確的HTML標(biāo)簽，都能夠使用（除了像

這種標(biāo)題標(biāo)簽，因?yàn)閖avac會(huì)插入自己的標(biāo)題，容易引起沖突）。如下例(摘自《Java編程思想》)：

/**

*

* System.out.println(new Date());
* 

*

* 您 甚至可以插入一個(gè)列表：

*

*

1. 項(xiàng)目一

   *

2. 項(xiàng)目二

   *

3. 項(xiàng)目三

   *

*/

這個(gè)標(biāo)記允許我們引用其他類的文檔，javac會(huì)生成相應(yīng)的HTML，直接鏈接到其他文檔中。格式如下：

@see 類名

@see 完整類名

@see 完整類名#方法名

每一格式都會(huì)在生成的文檔里自動(dòng)加入一個(gè)超鏈接的“See Also ”條目。(javadoc不會(huì)檢查我們指定的超鏈接，不會(huì)驗(yàn)證它們是否有效。)

@version 版本信息

“版本信息”代表任何適合作為版本說明的資料。若在javadoc命令行使用了“-version”標(biāo)記，就會(huì)從生成的 HTML 文檔里提取出版本信息。

變量文檔只能包括嵌入的 HTML 以及@see 引用。

除嵌入HTML和@see引用之外，方法還允許使用針對(duì)參數(shù)、返回值、異常的文檔標(biāo)記。

@param 參數(shù)名 說明

“參數(shù)名”是指參數(shù)列表內(nèi)的標(biāo)識(shí)符，而“說明”代表一些可延續(xù)到后續(xù)行內(nèi)的說明文字。一旦遇到一個(gè)新文檔標(biāo)記，就認(rèn)為前一個(gè)說明結(jié)束。可使用任意數(shù)量的說明，每個(gè)參數(shù)一個(gè)。

@return 說明

“說明”是指返回值的含義。它可延續(xù)到后面的行內(nèi)。

@exception 完整類名 說明

“完整類名”明確指定了一個(gè)違例類的名字，它是在其他某個(gè)地方定義好的。而“說明”（同樣可以延續(xù)到下面的行）告訴我們?yōu)槭裁催@種特殊類型的違例會(huì)在方法調(diào)用中出現(xiàn)。

@throws 完整類名 說明

與@exception同義。

@deprecated

該標(biāo)記用于指出一些舊功能已由改進(jìn)過的新功能取代。該標(biāo)記的作用是建議用戶不必再使用一種特定的功能，因?yàn)槲磥砀陌鏁r(shí)可能摒棄這一功能。若將一個(gè)方法標(biāo)記為@deprecated，則使用該方法時(shí)會(huì)收到編譯器的警告。

注：Java帶有的注釋標(biāo)記不止這些，這里只是介紹幾個(gè)比較常用的注釋標(biāo)記。

三、注釋技巧-算是拋磚引玉

注釋的目的主要有三點(diǎn)：

代碼整潔；

迅速理解代碼作用及原理；

形成文檔。

所以根據(jù)這兩年的經(jīng)驗(yàn)，總結(jié)幾條技巧，算是拋磚引玉。

在代碼中加入必要的空行及空白字符，可以使代碼分段清晰。對(duì)注釋提供規(guī)范的縮進(jìn)，協(xié)調(diào)美觀。

在代碼較長(zhǎng)或多重嵌套的情況下，應(yīng)該在一些段落結(jié)束處增加比較的注釋提示。

在注釋與注釋分隔符之間用一個(gè)空格隔開，可以比較容易找到注釋。

絕對(duì)不要給注釋添加邊框，如果增加了，這將是噩夢(mèng)的開始。

注釋長(zhǎng)度最好不大于80~120字符，否則在窄屏中查看起來很費(fèi)勁。

利用塊注釋作為代碼的開關(guān)：

下面代碼中打印1

//*

System.out.println(1);

/*/

System.out.println(2);

//*/

下面代碼中打印2

/*

System.out.println(1);

/*/

System.out.println(2);

//*/

對(duì)于程序中有兩段代碼需要切換的情況，這個(gè)還是很方便的，只需要在第一行增加或刪除“/”即可。(當(dāng)然，很多人在Eclipse中喜歡使用ctrl+/)

HTML Java

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。