Java代碼規範

1 注釋文檔的格式注釋文檔將用來產生HTML格式的代碼報告，所以注釋文檔必須書寫在類、域、建構函式、方法、定義之前。注釋文檔由兩部分組成——描述、塊標記。例如：/*** 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);}前兩行為描述，描述完畢後，由@符號起頭為塊標記注視。 <!--[if !supportLists]-->2<!--[endif]-->注釋的種類 2.1 檔案頭注釋檔案頭注釋以 /*開始，以*/結束，需要註明該檔案建立時間，檔案名稱，命名空間資訊。例如：/** Created on 2005-7-2* / 2.2 類、介面注釋類、介面的注釋採用 /** … */，描述部分用來書寫該類的作用或者相關資訊，塊標記部分必須註明作者和版本。例如：/**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 建構函式注釋建構函式注釋採用 /** … */，描述部分註明建構函式的作用，不一定有塊標記部分。例如：/*** 預設建構函式*/有例如：/*** 帶參數建構函式,初始化模式名,名稱和資料來源類型* * @param schema* Ref 模式名* @param name* Ref 名稱* @param type* byVal 資料來源類型*/ 2.4 域注釋域注釋可以出現在注釋文檔裡面，也可以不出現在注釋文檔裡面。用/** … */的域注釋將會被認為是注釋文檔熱出現在最終產生的HTML報告裡面，而使用/* … */的注釋會被忽略。例如：/* 由於triger和表用一個DMSource，所以要區分和表的遷移成功標記 */boolean isTrigerSuccess = false;又例如：/** 由於triger和表用一個DMSource，所以要區分和表的遷移成功標記 */boolean isTrigerSuccess = false;再例如：/*** The X-coordinate of the component.** @see #getLocation()*/int x = 1263732; 2.5 方法注釋方法注釋採用 /** … */，描述部分註明方法的功能，塊標記部分註明方法的參數，傳回值，異常等資訊。例如：/*** 設定是否有外碼約束* * @param conn* Connection 與資料庫的串連*/ 2.6 定義注釋規則同域注釋。 3 註解區塊標記 3.1 標記的順序塊標記將採用如下順序：…** @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)* …一個塊標記可以根據需要重複出現多次，多次出現的標記按照如下順序：@author 按照時間先後順序（chronological）@param 按照參數定義順序（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 標記介紹 3.2.1 @param標記@param後面空格後跟著參數的變數名字（不是類型），空格後跟著對該參數的描述。在描述中第一個名字為該變數的資料類型，表示資料類型的名次前面可以有一個冠詞如：a,an,the。如果是int類型的參數則不需要註明資料類型。例如：…* @param ch the char 用用來……* @param _image the image 用來……* @param _num一個數字………對於參數的描述如果只是一短語，最好不要首字母大寫，結尾也不要句號。對於參數的描述是一個句子，最好不要首字母大寫，如果出現了句號這說明你的描述不止一句話。如果非要首字母大寫的話，必須用句號來結束句子。（英文的句號）公司內部添加ByRef和ByVal兩個標記，例如：* @param _image the image ByRef 用來……說明該參數是引用傳遞（指標），ByVal可以省略，表示是值傳遞。 3.2.2 @return標記返回為空白（void）的建構函式或者函數，@return可以省略。如果傳回值就是輸入參數，必須用與輸入參數的@param相同的描述資訊。必要的時候註明特殊條件寫的傳回值。 3.2.3 @throws 標記@throws以前使用的是@exception。@throws的內容必須在函數的throws部分定義。 3.2.4 @author標記類注釋標記。函數注釋裡面可以不出現@author。 3.2.5 @version類注釋標記。函數注釋裡面可以不出現@version 3.2.6 @since類注釋標記。標明該類可以啟動並執行JDK版本例如：@since JDK1.2 3.2.7 @deprecated由於某種原因而被宣布將要被廢棄的方法。/*** @deprecated As of JDK 1.1, replaced by * setBounds* @see #setBounds(int,int,int,int)*/ 3.2.8 @link標記文法：{@link package.class#member label}Label為連結文字。package.class#member將被自動轉換成指向package.class的member檔案的URL。 4 HTML代碼的使用在注釋描述部分可以使用HTML代碼。

表示段落

表示自動標號

5 注釋樣本/*** Graphics is the abstract base class for all graphics contexts* which allow an application to draw onto components realized on* various devices or onto off-screen images.* A Graphics object encapsulates the state information needed* for the various rendering operations that Java supports. This* state information includes:

*

*

*

*

*

*

*

*

* (see setXORMode)*

*

* Coordinates are infinitely thin and lie between the pixels of the* output device.* Operations which draw the outline of a figure operate by traversing* along the infinitely thin path with a pixel-sized pen that hangs* down and to the right of the anchor point on the path.* Operations which fill a figure operate by filling the interior* of the infinitely thin path.* Operations which render horizontal text render the ascending* portion of the characters entirely above the baseline coordinate.

*

* Some important points to consider are that drawing a figure that* covers a given rectangle will occupy one extra row of pixels on* the right and bottom edges compared to filling a figure that is* bounded by that same rectangle.* Also, drawing a horizontal line along the same y coordinate as* the baseline of a line of text will draw the line entirely below* the text except for any descenders.* Both of these properties are due to the pen hanging down and to* the right from the path that it traverses.

*

* All coordinates which appear as arguments to the methods of this* Graphics object are considered relative to the translation origin* of this Graphics object prior to the invocation of the method.* All rendering operations modify only pixels which lie within the* area bounded by both the current clip of the graphics context* and the extents of the Component used to create the Graphics object.* * @author Sami Shaio* @author Arthur van Hoff* @version %I%, %G%* @since 1.0*/public abstract class Graphics {/** * Draws as much of the specified image as is currently available* with its northwest corner at the specified coordinate (x, y).* This method will return immediately in all cases, even if the* entire image has not yet been scaled, dithered and converted* for the current output device.

*

* If the current output representation is not yet complete then* the method will return false and the indicated * {@link ImageObserver} object will be notified as the* conversion process progresses.** @param img the image to be drawn* @param x the x-coordinate of the northwest corner* of the destination rectangle in pixels* @param y the y-coordinate of the northwest corner* of the destination rectangle in pixels* @param observer the image observer to be notified as more* of the image is converted. May be * null* @return true if the image is completely * loaded and was painted successfully; * false otherwise.* @see Image* @see ImageObserver* @since 1.0*/public abstract boolean drawImage(Image img, int x, int y, ImageObserver observer);/*** Dispose of the system resources used by this graphics context.* The Graphics context cannot be used after being disposed of.* While the finalization process of the garbage collector will* also dispose of the same system resources, due to the number* of Graphics objects that can be created in short time frames* it is preferable to manually free the associated resources* using this method rather than to rely on a finalization* process which may not happen for a long period of time.

*

* Graphics objects which are provided as arguments to the paint* and update methods of Components are automatically disposed* by the system when those methods return. Programmers should,* for efficiency, call the dispose method when finished using* a Graphics object only if it was created directly from a* Component or another Graphics object.** @see #create(int, int, int, int)* @see #finalize()* @see Component#getGraphics()* @see Component#paint(Graphics)* @see Component#update(Graphics)* @since 1.0*/public abstract void dispose();/*** Disposes of this graphics context once it is no longer * referenced.** @see #dispose()* @since 1.0*/public void finalize() {dispose();}}

The Component to draw on

A translation origin for rendering and clipping coordinates

The current clip

The current color

The current font

The current logical pixel operation function (XOR or Paint)

The current XOR alternation color

 

• ….

…