偶然看到新浪SDK中有一個類,詳細說明了他們在開發SDK的時候需要使用到的規範操作,個人覺得這比之于寫一份文檔好得多。清晰明了,關鍵是有對照物,這裡我直接複制該檔案,分享給大家。
/*
* 檔案名(可選),如 CodingRuler.java
*
* 版本資訊(可選),如:@version 1.0.0
*
* 版權申明(開源代碼一般都需要添加),如:Copyright (C) 2010-2013 SINA Corporation.
*/
package com.sina.weibo.sdk.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. 以下順序可供參考:
* 定義TAG,一般為 private(可選)<br>
* 定義 public 常量<br>
* 定義 private 常量、内部類<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
}
}
個中的細節,需要大家仔細體會。