代碼開發規範

CodingRuler.java

/*
 * 文件名（可選），如 CodingRuler.java
 * 
 * 版本信息（可選），如：@version 1.0.0
 * 
 * 版權申明（開源代碼通常都須要添加），如：Copyright (C) 2010-2013 SINA Corporation.
 */

package codestyle;

/**
 * 類的大致描述放在這裏。
 * 
 * <p>
 * <b>NOTE：如下部分爲一個簡要的編碼規範，更多規範請參考 ORACLE 官方文檔。</b><br>
 * 地址：http://www.oracle.com/technetwork/java/codeconventions-150003.pdf<br>
 * 另外，請使用 UTF-8 格式來查看代碼，避免出現中文亂碼。<br>
 * <b>至於註釋應該使用中文仍是英文，請本身行決定，根據公司或項目的要求而定，推薦使用英文。</b><br>
 * </p>
 * <h3>1. 整理代碼</h3>
 * <ul>
 *    <li>1.1. Java 代碼中不容許出如今警告，沒法消除的警告要用 @SuppressWarnings。
 *    <li>1.2. 去掉無用的包、方法、變量等，減小殭屍代碼。
 *    <li>1.3. 使用 Lint 工具來查看並消除警告和錯誤。
 *    <li>1.4. 使用 Ctrl+Shift+F 來格式化代碼，而後再進行調整。
 *    <li>1.5. 使用 Ctrl+Shift+O 來格式化 Import 包。
 * </ul>
 * 
 * <h3>2. 命名規則</h3>
 *    <h3>2.1. 基本原則</h3>
 *    <ul>
 *         <li>2.1.1. 變量，方法，類命名要表義，嚴格禁止使用 name1, name2 等命名。
 *         <li>2.1.2. 命名不能太長，適當使用簡寫或縮寫。（最好不要超過 25 個字母）
 *         <li>2.1.3. 方法名以小寫字母開始，之後每一個單詞首字母大寫。
 *         <li>2.1.4. 避免使用類似或者僅在大小寫上有區別的名字。
 *         <li>2.1.5. 避免使用數字，但可用 2 代替 to，用 4 代替 for 等，如 go2Clean。
 *     </ul>
 *    
 *    <h3>2.2. 類、接口</h3>
 *    <ul>
 *         <li>2.2.1. 全部單詞首字母都大寫。使用能確切反應該類、接口含義、功能等的詞。通常採用名詞。
 *         <li>2.2.2. 接口帶 I 前綴，或able, ible, er等後綴。如ISeriable。
 *    </ul>
 *    
 *    <h3>2.3. 字段、常量</h3>
 *    <ul>
 *         <li>2.3.1. 成員變量以 m 開頭，靜態變量以 s 開頭，如 mUserName, sInstance。
 *         <li>2.3.2. 常量所有大寫，在詞與詞以前用下劃線鏈接，如 MAX_NUMBER。
 *         <li>2.3.3. 代碼中禁止使用硬編碼，把一些數字或字符串定義成經常使用量。
 *         <li>2.3.4. 對於廢棄不用的函數，爲了保持兼容性，一般添加 @Deprecated，如 {@link #doSomething()}
 *    </ul>
 *         
 * <h3>3. 註釋</h3>
 *    請參考 {@link #SampleCode} 類的註釋。
 *    <ul>
 *    <li>3.1. 常量註釋，參見 {@link #ACTION_MAIN} 
 *    <li>3.2. 變量註釋，參見 {@link #mObject0} 
 *    <li>3.3. 函數註釋，參見 {@link #doSomething(int, float, String)}
 *    </ul> 
 *    
 * <h3>4. Class 內部順序和邏輯</h3>
 * <ul>
 *    <li>4.1. 每一個 class 都應該按照必定的邏輯結構來排列基成員變量、方法、內部類等，
 *             從而達到良好的可讀性。
 *    <li>4.2. 整體上來講，要按照先 public, 後 protected, 最後 private, 函數的排布
 *             也應該有一個邏輯的前後順序，由重到輕。
 *    <li>4.3. 如下順序可供參考：<br>
 *         定義TAG，通常爲 private（可選）<br>
 *         定義 public 常量<br>
 *         定義 protected 常量、內部類<br>
 *         定義 private 變量<br>
 *         定義 public 方法<br>
 *         定義 protected 方法<br>
 *         定義 private 方法<br>
 * </ul>        
 * 
 * <h3>5. 表達式與語句</h3>
 *    <h3>5.1. 基本原則：採用緊湊型風格來編寫代碼</h3>
 *    <h3>5.2. 細則</h3>
 *    <ul>
 *         <li>5.2.1. 條件表示式，參見 {@link #conditionFun(boolean)} 
 *         <li>5.2.2. switch 語句，參見 {@link #switchFun(int)}
 *         <li>5.2.3. 循環語句，參見 {@link #circulationFun(boolean)}
 *         <li>5.2.4. 錯誤與異常，參見 {@link #exceptionFun()}
 *         <li>5.2.5. 雜項，參見 {@link #otherFun()}
 *         <li>5.2.6. 批註，參見 {@link #doSomething(int, float, String)}
 *     </ul>
 * 
 * @author 做者名
 * @since 2013-XX-XX
 */
@SuppressWarnings("unused")
public class CodingRuler {

    /** 公有的常量註釋 */
    public static final String ACTION_MAIN = "android.intent.action.MAIN";
    
    /** 私有的常量註釋（同類型的常量能夠分塊並緊湊定義） */
    private static final int MSG_AUTH_NONE    = 0;
    private static final int MSG_AUTH_SUCCESS = 1;
    private static final int MSG_AUTH_FAILED  = 2;
    
    /** 保護的成員變量註釋 */
    protected Object mObject0;
    
    /** 私有的成員變量 mObject1 註釋（同類型的成員變量能夠分塊並緊湊定義） */
    private Object mObject1;
    /** 私有的成員變量 mObject2 註釋 */
    private Object mObject2;
    /** 私有的成員變量 mObject3 註釋 */
    private Object mObject3;
    
    /**
     * 對於註釋多於一行的，採用這種方式來
     * 定義該變量
     */
    private Object mObject4;

    /**
     * 公有方法描述...
     * 
     * @param param1  參數1描述...
     * @param param2  參數2描述...
     * @param paramXX 參數XX描述... （注意：請將參數、描述都對齊）
     */
    public void doSomething(int param1, float param2, String paramXX) {
        // 如下注釋標籤能夠經過Eclipse內置的Task插件看到
        // TODO  使用TODO來標記代碼，說明標識處有功能代碼待編寫
        // FIXME 使用FIXME來標記代碼，說明標識處代碼須要修正，甚至代碼是
        //       錯誤的，不能工做，須要修復
        // XXX   使用XXX來標記代碼，說明標識處代碼雖然實現了功能，可是實現
        //       的方法有待商榷，但願未來能改進
    }
    
    /**
     * 保護方法描述...
     */
    @Deprecated
    protected void doSomething() {
        // ...implementation
    }
    
    /**
     * 私有方法描述...
     * 
     * @param param1  參數1描述...
     * @param param2  參數2描述...
     */
    private void doSomethingInternal(int param1, float param2) {
        // ...implementation        
    }
    
    /**
     * 條件表達式原則。
     */
    private void conditionFun() {
        boolean condition1 = true;
        boolean condition2 = false;
        boolean condition3 = false;
        boolean condition4 = false;
        boolean condition5 = false;
        boolean condition6 = false;
        
        // 原則： 1. 全部 if 語句必須用 {} 包括起來，即使只有一句，禁止使用不帶{}的語句
        //       2. 在含有多種運算符的表達式中，使用圓括號來避免運算符優先級問題
        //       3. 判斷條件不少時，請將其它條件換行
        if (condition1) {
            // ...implementation
        }
        
        if (condition1) {
            // ...implementation
        } else {
            // ...implementation
        }
        
        if (condition1)          /* 禁止使用不帶{}的語句 */
            condition3 = true;
        
        if ((condition1 == condition2) 
                || (condition3 == condition4)
                || (condition5 == condition6)) {
            
        }
    }
    
    /**
     * Switch語句原則。
     */
    private void switchFun() {
        
        // 原則： 1. switch 語句中，break 與下一條 case 之間，空一行
        //       2. 對於不須要 break 語句的，請使用 /* Falls through */來標註
        //       3. 請默認寫上 default 語句，保持完整性
        int code = MSG_AUTH_SUCCESS;
        switch (code) {
        case MSG_AUTH_SUCCESS:
            break;
            
        case MSG_AUTH_FAILED:
            break;
            
        case MSG_AUTH_NONE:
            /* Falls through */
        default:
            break;
        }
    }
    
    /**
     * 循環表達式。
     */
    private void circulationFun() {
        
        // 原則： 1. 儘可能使用for each語句代替原始的for語句
        //       2. 循環中必須有終止循環的條件或語句，避免死循環
        //       3. 循環要儘量的短, 把長循環的內容抽取到方法中去
        //       4. 嵌套層數不該超過3層, 要讓循環清晰可讀
        
        int array[] = { 1, 2, 3, 4, 5 };
        for (int data : array) {
            // ...implementation
        }
        
        int length = array.length;
        for (int ix = 0; ix < length; ix++) {
            // ...implementation
        }
        
        boolean condition = true;
        while (condition) {
            // ...implementation
        }
        
        do {
            // ...implementation
        } while (condition);
    }
    
    /**
     * 異常捕獲原則。
     */
    private void exceptionFun() {
        
        // 原則： 1. 捕捉異常是爲了處理它，一般在異常catch塊中輸出異常信息。
        //       2. 資源釋放的工做，能夠放到 finally 塊部分去作。如關閉 Cursor 等。
        try {
            // ...implementation
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            
        }
    }
    
    /**
     * 其它原則（整理中...）。
     */
    private void otherFun() {
        // TODO
    }    
}

SampleCode.java

/*
 * Copyright (C) 2010-2013 The SINA WEIBO Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package codestyle;

/**
 * 類的大致描述放在這裏。
 *         
 * @author 做者名
 * @since 2013-XX-XX
 */
@SuppressWarnings("unused")
public class SampleCode {

    /** 公有的常量註釋 */
    public static final String ACTION_MAIN = "android.intent.action.MAIN";
    
    /** 私有的常量註釋（同類型的常量能夠分塊並緊湊定義） */
    private static final int MSG_AUTH_NONE    = 0;
    private static final int MSG_AUTH_SUCCESS = 1;
    private static final int MSG_AUTH_FAILED  = 2;
    
    /** 保護的成員變量註釋 */
    protected Object mObject0;
    
    /** 私有的成員變量 mObject1 註釋（同類型的成員變量能夠分塊並緊湊定義） */
    private Object mObject1;
    /** 私有的成員變量 mObject2 註釋 */
    private Object mObject2;
    /** 私有的成員變量 mObject3 註釋 */
    private Object mObject3;
    
    /**
     * 對於註釋多於一行的，採用這種方式來
     * 定義該變量
     */
    private Object mObject4;

    /**
     * 公有方法描述...
     * 
     * @param param1  參數1描述...
     * @param param2  參數2描述...
     * @param paramXX 參數XX描述... （注意：請將參數、描述都對齊）
     */
    public void doSomething(int param1, float param2, String paramXX) {
        // ...implementation
    }
    
    /**
     * 保護方法描述...
     */
    protected void doSomething() {
        // ...implementation        
    }
    
    /**
     * 私有方法描述...
     * 
     * @param param1  參數1描述...
     * @param param2  參數2描述...
     */
    private void doSomethingInternal(int param1, float param2) {
        // ...implementation        
    }
}