註解

Posted by Bruce Tsai

撰寫註解的原則

• 註解為必要的內容，不得省略，撰寫的目的不在於自己查看，而是讓別人能快速理解
• 註解的內容需包含程式所要達成的目的，而不是程式碼的內容
• 類別的註解，包含作者、程式說明、建立日期等
• 方法的註解，包含功能說明、參數意義、回傳值等
• 邏輯與流程的註解，在開發前可先以 TODO 的方式撰寫邏輯與流程註解，並在開發完成後將 TODO 移除

狀況:什麼都沒寫

public NetworkRateChangeInitData getNetworkRateChangeInitData() {
    Privilege privilege = customer.getProductPrivilege(msisdn);
    boolean is4G = 
           privilege == Privilege.Postpaid4G 
        || privilege == Privilege.Prepaid4G;
    // more code here
}

正確做法：儘可能將標註相關邏輯及流程

/**
 * 取得網路費率基本資料
 * @return
 */
public NetworkRateChangeInitData getNetworkRateChangeInitData() {
    // 1. 取得權限並判斷，若為4G時僅顯示特定訊息
    Privilege privilege = customer.getProductPrivilege(msisdn);
    boolean is4G = 
           privilege == Privilege.Postpaid4G 
        || privilege == Privilege.Prepaid4G;
    // more code here
}