Programs Knowledge

Variables

變數與常數名稱, 格式如下:

字首prefix(optional) + 主體body

字首標明此名稱是什麼物件或是什麼變數型態, 通常是1至3個小寫字母.

主體標明此名稱的意義, 由數個字組成, 每個字的第一個字母大寫, 每個字相連不含空白.

舉例來說, nUserId, n表示此變數為一個整數, 其字首為n. 主體為UserId

字首與對應的型態列表.

Class Variables, Method Variables

區域物件變數 (Class Variable): 不需要字首, 主體第一個字完全小寫, 其他每個字的第一個字母大寫. ex userId.

Constants (常數)

不需要字首, 每個字母都大寫,字與字之間用底線(_)相連. ex: MIN_COUNT.

Class/Interface

Class名稱原則上由數個字組成, 每個字的第一個字母大寫, 每個字相連不含空白. ex, UtilFunc

Class Method

如同變數命名方式,不需要字首,第一個字完全小寫. 最好第一個字是動詞以表示動作.

ex, reverseString(), getInfo()等等.

Package

com.domain.identifier.subidentifier…

¨ 如果為了確認套件的唯一性(unique)，須在套件名稱前加上公司的網域名字(com.domain)，再加上identifier，identifier建議為模組名稱或子模組名稱。

¨ 所有的套件名稱必需是由小寫的單數名詞所組成的。如com.abc.personal.util等等

Exception

Module exception name

¨ 為了簡化每個模組(Module)對exception的處理，每個模組最好都有屬於自已特定的exception。

¨ 命名時前面為模組名稱(Module name)，為增加可讀性建議再加上Exception種類, ex: ModuleNameConnectionTimeoutException

Comments

標題註解

說明此檔案之用途或內部所包含的函數或副程式, 應包括下述幾個基本要件: 版權及保密等級,檔案內容或功能的文字描述,修改記錄.

 * Copyright(c) 2012 ComponyName. All Rights Reserved.
 * 
 * Description   : 
 * Written by    : 
 * Date              : 
 * Change Log - 
 * Date    version    author    description
 * ==============================================================
 * 20120619  1.00    Mark    ...
 * 20130415  1.00    Jeff      ...
 */

區塊註解

區塊註解使用於解釋 檔案, methods, 資料結構 和 演算法. 在每一個檔案 或method的內部加上區塊註解.

Example:

 
 * Here is a block comment. 
 */

單行註解

單行註解置於statement的上方或statement的右方. 用於描述一個statement. 使用/*…*/ 或 // 區隔.

Example:

{    
    /* Handle the condition. */    
    return TRUE;
} 
else 
{    
    return FALSE;  // other cases
}

Class and Interface comments

Class 或 Interface 的宣告之前, 必須加入 Documentation comment. 解釋Class, Interface的用途, 作者, 版本等.

*
 *  Class comment
 */
public class Point
{
    ...
}

Method and Member comments

Method或Member的宣告之前, 必須加入 Documentation comment. 解釋Method, Member的用途, 每一個參數的意義, 傳回值的意義, Exception等.

 * Put description here    
 @param    filePath    a string of file path
 @param    fileName  a string of file name               
 @return    a boolean means success or fail
 @throws   IOException    if open file error
 */

Others

l 程式對齊: 每次內縮4個字元或一個Tab(Tab鍵設定為4個字母,請僅量使用 Tab).

l 避免複雜: 為了便於程式的可讀性與偵錯, 一個原始程式行上不要有多於一個以上的程式指令. 如果需要30秒以上才能瞭解一行敘述, 試著簡化之.

l 函數或程序呼叫:

折行後的參數必須和前一行的第一個參數對齊.

classMethod (parameter1, parameter2, parameter3,

                   parameter4, parameter5, parameter6);