Java編碼規(guī)范: 盡量使用完整的英文描述符采用適用于相關(guān)領(lǐng)域的術(shù)語采用大小寫混合使名字可讀盡量少用縮寫，但如果用了，必須符合整個工程中的統(tǒng)一定義避免使用長的名字（小于15個字母為正常選擇）避免使用類似的名字，或者僅僅是大小寫不同的名字避免使用下劃線（除靜態(tài)常量等）標(biāo)識符類型說明包（Package）的命名Package的名字應(yīng)該采用完整的英文描述符，都是由一個小寫單詞組成。并且包名的前綴總是一個頂級域名
成都創(chuàng)新互聯(lián)公司主營含山網(wǎng)站建設(shè)的網(wǎng)絡(luò)公司,主營網(wǎng)站建設(shè)方案,成都App定制開發(fā),含山h5成都微信小程序搭建,含山網(wǎng)站營銷推廣歡迎含山等地區(qū)企業(yè)咨詢
，通常是com、edu、gov、mil、net、org等；如：com.yjhmily.test類（Class）的命名類名應(yīng)該是個一名詞，采用大小寫混合的方式，每個單詞的首字母大寫。盡量保證類名簡潔而富于描述。
定義規(guī)范的目的是讓項目中所有的文檔都看起來像一個人寫的，增加可讀性，減少項目組中因為換人而帶來的損失。（這些規(guī)范并不是一定要絕對遵守，但是一定要讓程序有良好的可讀性）。
// 注釋一行 ?
/* ...... */ 注釋若干行 ?
/** ...... */ 注釋若干行，并寫入 javadoc 文檔
如下代碼：
package?com.qiu.lin.he;
/**
*?第三種注釋方式
*?@author?Administrator
*
*/
public?class?CeShi?{
public?static?void?main(String[]?args)?{
int?str?=?107653;
//System.out.print(str?/?(24?*?60?*?60)?+?"天");
/*System.out.print(str?%?(24?*?60?*?60)?/?(60?*?60)?+?"小時");
System.out.print(str?%?(24?*?60?*?60)?%?(60?*?60)?/?60?+?"分鐘");*/
System.out.print(str?%?(24?*?60?*?60)?%?(60?*?60)?%?60?+?"秒");
}
}
暈~~~ 自己還是找到了 ·· 留給后來人吧···
java文檔注釋（有示例）
Java代碼規(guī)范--注釋
@author LEI
@version 1.10 2005-09-01
1 注釋文檔的格式注釋文檔將用來生成HTML格式的代碼報告，所以注釋文檔必須書寫在類、域、構(gòu)造函數(shù)、方法、定義之前。注釋文檔由兩部分組成——描述、塊標(biāo)記。
例如：
/**
* The doGet method of the servlet.
* This method is called when a form has its tag value method equals to get.
*
* @param request
* the request send by the client to the server
* @param response
* the response send by the server to the client
* @throws ServletException
* if an error occurred
* @throws IOException
* if an error occurred
*/
public void doGet (HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
doPost(request, response);
}
前兩行為描述，描述完畢后，由@符號起頭為塊標(biāo)記注視。
2 注釋的種類2.1 文件頭注釋
文件頭注釋以 /*開始，以*/結(jié)束，需要注明該文件創(chuàng)建時間，文件名，命名空間信息。
例如：
/*
* Created on 2005-7-2
* /
2.2 類、接口注釋
類、接口的注釋采用 /** … */，描述部分用來書寫該類的作用或者相關(guān)信息，塊標(biāo)記部分必須注明作者和版本。
例如：
/**Title: XXXX DRIVER 3.0
*Description: XXXX DRIVER 3.0
*Copyright: Copyright (c) 2003
*Company:XXXX有限公司
*
* @author Java Development Group
* @version 3.0
*/
例如：
/**
* A class representing a window on the screen.
* For example:
*
* Window win = new Window(parent);
* win.show();
*
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
2.3 構(gòu)造函數(shù)注釋
構(gòu)造函數(shù)注釋采用 /** … */，描述部分注明構(gòu)造函數(shù)的作用，不一定有塊標(biāo)記部分。
例如：
/**
* 默認(rèn)構(gòu)造函數(shù)
*/
有例如：
/**
* 帶參數(shù)構(gòu)造函數(shù),初始化模式名,名稱和數(shù)據(jù)源類型
*
* @param schema
* Ref 模式名
* @param name
* Ref 名稱
* @param type
* byVal 數(shù)據(jù)源類型
*/
2.4 域注釋
域注釋可以出現(xiàn)在注釋文檔里面，也可以不出現(xiàn)在注釋文檔里面。用/** … */的域注釋將會被認(rèn)為是注釋文檔熱出現(xiàn)在最終生成的HTML報告里面，而使用/* … */的注釋會被忽略。
例如：
/* 由于triger和表用一個DMSource，所以要區(qū)分和表的遷移成功標(biāo)記 */
boolean isTrigerSuccess = false;
又例如：
/** 由于triger和表用一個DMSource，所以要區(qū)分和表的遷移成功標(biāo)記 */
boolean isTrigerSuccess = false;
再例如：
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
2.5 方法注釋
方法注釋采用 /** … */，描述部分注明方法的功能，塊標(biāo)記部分注明方法的參數(shù)，返回值，異常等信息。例如：
/**
* 設(shè)置是否有外碼約束
*
* @param conn
* Connection 與數(shù)據(jù)庫的連接
*/
2.6 定義注釋
規(guī)則同域注釋。
3 注釋塊標(biāo)記3.1 標(biāo)記的順序
塊標(biāo)記將采用如下順序：
…
*
* @param (classes, interfaces, methods and constructors only)
* @return (methods only)
* @exception (@throws is a synonym added in Javadoc 1.2)
* @author (classes and interfaces only, required)
* @version (classes and interfaces only, required. See footnote 1)
* @see
* @since
* @serial (or @serialField or @serialData)
* @deprecated (see How and When To Deprecate APIs)
* …
一個塊標(biāo)記可以根據(jù)需要重復(fù)出現(xiàn)多次，多次出現(xiàn)的標(biāo)記按照如下順序：
@author 按照時間先后順序（chronological）
@param 按照參數(shù)定義順序（declaration）
@throws 按照異常名字的字母順序（alphabetically）
@see 按照如下順序：
@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package
3.2 標(biāo)記介紹
3.2.1 @param標(biāo)記
@param后面空格后跟著參數(shù)的變量名字（不是類型），空格后跟著對該參數(shù)的描述。
在描述中第一個名字為該變量的數(shù)據(jù)類型，表示數(shù)據(jù)類型的名次前面可以有一個冠詞如：a,an,the。如果是int類型的參數(shù)則不需要注明數(shù)據(jù)類型。例如：
…
* @param ch the char 用用來……
* @param _image the image 用來……
* @param _num 一個數(shù)字……
…
對于參數(shù)的描述如果只是一短語，最好不要首字母大寫，結(jié)尾也不要句號。
對于參數(shù)的描述是一個句子，最好不要首字母大寫，如果出現(xiàn)了句號這說明你的描述不止一句話。如果非要首字母大寫的話，必須用句號來結(jié)束句子。（英文的句號）
公司內(nèi)部添加ByRef和ByVal兩個標(biāo)記，例如：
* @param _image the image ByRef 用來……
說明該參數(shù)是引用傳遞（指針），ByVal可以省略，表示是值傳遞。
3.2.2 @return標(biāo)記
返回為空（void）的構(gòu)造函數(shù)或者函數(shù)，@return可以省略。
如果返回值就是輸入?yún)?shù)，必須用與輸入?yún)?shù)的@param相同的描述信息。
必要的時候注明特殊條件寫的返回值。
3.2.3 @throws 標(biāo)記
@throws以前使用的是@exception。
@throws的內(nèi)容必須在函數(shù)的throws部分定義。
3.2.4 @author標(biāo)記
類注釋標(biāo)記。
函數(shù)注釋里面可以不出現(xiàn)@author。
3.2.5 @version
類注釋標(biāo)記。
文章出處：
/**
*?方法功能描述
*?
*?@param?參數(shù)說明
*?@author??作者
*?@return?返回格式
*?@exception??異常
*/
注釋是為了方便自己或代碼維護(hù)方更容易地讀懂代碼的用處。
一、背景?
1、當(dāng)我們第一次接觸某段代碼，但又被要求在極短的時間內(nèi)有效地分析這段代碼，我們需要什么樣的注釋信息？?
2、怎么樣避免我們的注釋冗長而且凌亂不堪呢？?
3、在多人協(xié)同開發(fā)、維護(hù)的今天，我們需要怎么樣的注釋來保證高質(zhì)、高交的進(jìn)行開發(fā)和維護(hù)工作呢？?
二、意義?
程序中的注釋是程序設(shè)計者與程序閱讀者之間通信的重要手段。應(yīng)用注釋規(guī)范對于軟件本身和軟件開發(fā)人員而言尤為重要。并且在流行的敏捷開發(fā)思想中已經(jīng)提出了將注釋轉(zhuǎn)為代碼的概念。好的注釋規(guī)范可以盡可能的減少一個軟件的維護(hù)成本?,?并且?guī)缀鯖]有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護(hù)。好的注釋規(guī)范可以改善軟件的可讀性，可以讓開發(fā)人員盡快而徹底地理解新的代碼。好的注釋規(guī)范可以最大限度的提高團(tuán)隊開發(fā)的合作效率。長期的規(guī)范性編碼還可以讓開發(fā)人員養(yǎng)成良好的編碼習(xí)慣，甚至鍛煉出更加嚴(yán)謹(jǐn)?shù)乃季S能力。?
三、注釋的原則?
1、 注釋形式統(tǒng)一?
在整個應(yīng)用程序中，使用具有一致的標(biāo)點和結(jié)構(gòu)的樣式來構(gòu)造注釋。如果在其他項目組發(fā)現(xiàn)他們的注釋規(guī)范與這份文檔不同，按照他們的規(guī)范寫代碼，不要試圖在既成的規(guī)范系統(tǒng)中引入新的規(guī)范。?
2、 注釋的簡潔?
內(nèi)容要簡單、明了、含義準(zhǔn)確，防止注釋的多義性，錯誤的注釋不但無益反而有害。?
3、 注釋的一致性?
在寫代碼之前或者邊寫代碼邊寫注釋，因為以后很可能沒有時間來這樣做。另外，如果有機(jī)會復(fù)查已編寫的代碼，在今天看來很明顯的東西六周以后或許就不明顯了。通常描述性注釋先于代碼創(chuàng)建，解釋性注釋在開發(fā)過程中創(chuàng)建，提示性注釋在代碼完成之后創(chuàng)建。修改代碼的同時修改相應(yīng)的注釋，以保證代碼與注釋的同步。?
4、 注釋的位置?
保證注釋與其描述的代碼相鄰，即注釋的就近原則。對代碼的注釋應(yīng)放在其上方相鄰或右方的位置，不可放在下方。避免在代碼行的末尾添加注釋；行尾注釋使代碼更難閱讀。不過在批注變量聲明時，行尾注釋是合適的；在這種情況下，將所有行尾注釋要對齊。?
5、 注釋的數(shù)量?
注釋必不可少，但也不應(yīng)過多，在實際的代碼規(guī)范中，要求注釋占程序代碼的比例達(dá)到20%左右。注釋是對代碼的“提示”，而不是文檔，程序中的注釋不可喧賓奪主，注釋太多了會讓人眼花繚亂，注釋的花樣要少。不要被動的為寫注釋而寫注釋。?
6、刪除無用注釋?
在代碼交付或部署發(fā)布之前，必須刪掉臨時的或無關(guān)的注釋，以避免在日后的維護(hù)工作中產(chǎn)生混亂。?
7、 復(fù)雜的注釋?
如果需要用注釋來解釋復(fù)雜的代碼，請檢查此代碼以確定是否應(yīng)該重寫它。盡一切可能不注釋難以理解的代碼，而應(yīng)該重寫它。盡管一般不應(yīng)該為了使代碼更簡單便于使用而犧牲性能，但必須保持性能和可維護(hù)性之間的平衡。?
8、 多余的注釋?
描述程序功能和程序各組成部分相互關(guān)系的高級注釋是最有用的，而逐行解釋程序如何工作的低級注釋則不利于讀、寫和修改，是不必要的，也是難以維護(hù)的。避免每行代碼都使用注釋。如果代碼本來就是清楚、一目了然的則不加注釋，避免多余的或不適當(dāng)?shù)淖⑨尦霈F(xiàn)。?
9、必加的注釋?
典型算法必須有注釋。在代碼不明晰或不可移植處必須有注釋。在代碼修改處加上修改標(biāo)識的注釋。在循環(huán)和邏輯分支組成的代碼中添加注釋。為了防止問題反復(fù)出現(xiàn)，對錯誤修復(fù)和解決方法的代碼使用注釋，尤其是在團(tuán)隊環(huán)境中。?
10、注釋在編譯代碼時會被忽略，不編譯到最后的可執(zhí)行文件中，所以注釋不?
會增加可執(zhí)行文件的大小。?
四、JAVA注釋技巧?
1、空行和空白字符也是一種特殊注釋。利用縮進(jìn)和空行，使代碼與注釋容易區(qū)?
別，并協(xié)調(diào)美觀。?
2、當(dāng)代碼比較長，特別是有多重嵌套時，為了使層次清晰，應(yīng)當(dāng)在一些段落的?
結(jié)束處加注釋（在閉合的右花括號后注釋該閉合所對應(yīng)的起點），注釋不能?
寫得很長，只要能表示是哪個控制語句控制范圍的結(jié)束即可，這樣便于閱讀。?
3、將注釋與注釋分隔符用一個空格分開，在沒有顏色提示的情況下查看注釋時，?
這樣做會使注釋很明顯且容易被找到。?
4、不允許給塊注釋的周圍加上外框。這樣看起來可能很漂亮，但是難于維護(hù)。?
5、每行注釋（連同代碼）不要超過120個字(1024×768)，最好不要超過80?
字(800×600)?。?
6、Java編輯器（IDE）注釋快捷方式。Ctrl+/?注釋當(dāng)前行,再按則取消注釋。?
7、對于多行代碼的注釋，盡量不采用“/*......*/”，而采用多行“//”注釋，?
這樣雖然麻煩，但是在做屏蔽調(diào)試時不用查找配對的“/*......*/”。?
8、注釋作為代碼切換開關(guān)，用于臨時測試屏蔽某些代碼。
重慶分公司
重慶分公司
