標準的Java編碼規範手冊
編碼規範體現出一個開發者的基本素質,良好的編碼規範可以提高團隊編碼的效率,避免很多不必要的問題。今天分享一個標準的Java編碼規範給大家,希望對於大家今後的開發工作帶來幫助。
編碼規範的意義
在專案開發維護中,編碼規範作為開發規範的一個組成部分,是十分重要和必須的,它不僅僅是為了提高開發效率,也有利於降低後期維護開發的成本。編碼規範的根本目的就是要讓不僅程式碼可以一目瞭然,也可以很容易的理解開發人員所編寫的程式碼程的用途和意義。由此,用來減少專案中因為開發維護人員的更替或由於長時間不維護造成的記憶模糊或混亂等情況帶來的對程式碼所實現的真正功能的理解困難和歧義。另外也提高了程式碼複查效率和效果。
規範實施建議
不是為了規範而規範,以提高軟體開發質量和效率為目標,輔以IDE等開發工具為保障,逐步改進編碼規範化水平
對於格式規範、註釋規範等部分規範的要求,可以通過使用eclipse/AndroidStudio自帶的Format方法(快捷鍵:Ctrl+Shift+F)進行自動格式化,可以提高開發效率又符合編碼規範。
編碼規範文件本身需要定期不斷的修正和完善,以符合實際開發規範的要求。
格式規範
a)縮排
使用配置檔案進行格式化:
配置檔案中一個TAB等於4個空格。
b)行長度
每行100字元
注: 使用eclipse自帶的Format方法(快捷鍵:Ctrl+Shift+F)時,需要配置“Maximum line width”設定長度為100
c)宣告
d)宣告變數、常量
一行只宣告一個變數或常量;
在程式碼塊的開始處宣告例項變數,不要在首次用到該變數時才宣告【推薦】
e)宣告類
左大括號”{“位於宣告語句同行的末尾,右大括號”}”另起一行;
方法與方法之間以空行分隔
f)語句
可以使用eclipse自帶的Format方法(快捷鍵:Ctrl+Shift+F)時 使用eclipse預設的“Control Statements ”格式化方法進行
注:if語句總是用”{“和”}”括起來
示例
class Example {
void bar() {
do {
} while (true);
try {
} catch (Exception e) {
} finally {
}
}
void foo2() {
if (true) {
return;
}
if (true) {
return;
} else if (false) {
return;
} else {
return;
}
}
}
g)空格的使用
等號左右必須各有一個空格:
button = null;
雙目運算子左右必須各有一個空格:
imageWidth = imagePadding + imageSize;
標點符號後面必須跟一個空格
標點符號包括“,”、“;”等,下面列出幾個例子。
一行定義多個變數時,“,”後跟空格:
int i, j;
在for迴圈中,“;”後跟空格:
for (int i = 0; i < count; ++i)
在有多個入口引數的函式呼叫中,“,”後跟一個空格:
addContentView(view, params);
h)變數型別的使用
程式設計的過程中儘量使用介面程式設計,而少用類程式設計。
如:
List<String> names = new ArrayList<String>();
命名規範
通用規則
命名規範使程式更易讀,從而更易於理解。它們也可以提供一些有關識別符號功能的資訊,以助於理解程式碼,例如,不論它是一個常量,包,還是類。
包(Packages) 一個唯一包名的字首總是全部小寫的ASCII字母並且是一個頂級域名,通常是com,edu,gov,mil,net,org,或1981年ISO 3166標準所指定的標識國家的英文雙字元程式碼。包名的後續部分根據不同機構各自內部的命名規範而不盡相同。這類命名規範可能以特定目錄名的組成來區分部門(department),專案(project),機器(machine),或註冊名(login names)。
如:
package com.itotem.view
package com.itotem.utils.xxxx
類(Classes) 命名規則:類名是個一名詞,採用大小寫混合的方式,每個單詞的首字母大寫。儘量使類名簡潔而富於描述。使用完整單詞,避免縮寫詞(除非該縮寫詞被更廣泛使用,像URL,HTML)
如:
public class Button
public class EditText
介面(Interfaces) 命名規則:介面類名以大寫“I”開頭,大小寫規則與類名相似,
如:
public interface IProjGroupService
方法(Methods) 方法名是一個動詞,採用大小寫混合的方式,第一個單詞的首字母小寫,其後單詞的首字母大寫。
如:
public void onCreate(Bundle savedInstanceState)
public void run()
區域性變數(Local Variables) 採用大小寫混合的方式,第一個單詞的首字母小寫,其後單詞的首字母大寫。變數名應簡短且富於描述。變數名的選用應該易於記憶,即,能夠指出其用途。儘量避免單個字元的變數名,除非是一次性的臨時變數。臨時變數通常被取名為i,j,k,m和n,它們一般用於整型。c,d,e,它們一般用於字元型,變數名不應以下劃線或美元符號開頭。
如:
int i = 0;
float imageWidth = 0;
例項變數(Instance Variables) 大小寫規則和類名相似,除了前面需要一個m。
如:
private int mEmployeeId = 0;
private String mName = "";
若例項變數為public型別的則和區域性變數採用相同的命名規則。
如:
public int width = 0;
public String contactName = "";
常量(Constants [採用stiatc final 修飾]) 類常量的宣告,應該全部大寫,單詞間用下劃線隔開。(類似C語言的巨集定義)。
如:
private static final int MIN_WIDTH = 4;
private static final int MAX_WIDTH = 999;
資源id 資源id全部採用小寫,單詞之間用下劃線隔開。
注意:這個小寫規範是Android強制執行的,如果出現大寫或者特殊字元工程是不能編譯的。會報錯
如:
download
app_name
call_log_type
備註(Remark)
所有的識別符號名稱要求取有意義的單詞,不能使用myXXXX和button01等風格的名稱。
附加說明
1、從命名中可以直觀看懂其定義和用途,否則必須增加註釋說明;
2、在同一系統內命名必須保持統一;避免出現類似示例中的情況;
示例:專案組id 變數定義:pgid、projectgroupId、idprojectgroup、idProjGroup
3、避免名字過長、命名採用英文縮寫,避免使用漢語拼音【推薦】
組織規範
引入包規範
不允許引入類中未使用的包;
引入包時不能直接引入“.*”,必須明確到引入的類名
可以通過快捷鍵引入包。Ctrl+Shift+O;
註釋規範
a)通用註釋規則
b)說明
註釋要精簡併清晰容易理解;
保持註釋與程式碼同步。
程式碼質量不好但能正常執行,或者還沒有實現的程式碼用 //TODO:任務 ;
存在錯誤隱患的程式碼用 //FIXME:宣告;
對於不建議使用(廢棄)的類或者方法,必須在他們的註釋中增加 @deprecated
c)javadoc註釋標籤語法定義說明
@author 對類的說明 標明開發該類模組的作者
@version 對類的說明 標明該類模組的版本
@see 對類、屬性、方法的說明 參考轉向,也就是相關主題
@param 對方法的說明 對方法中某引數的說明
@return 對方法的說明 對方法返回值的說明
@exception 對方法的說明 對方法可能丟擲的異常進行說
@deprecated 對類或方法的說明 該類或方法不建議使用
d)類的註釋
目的:簡單概述該類作用
範圍:所有java類,可以不包括javabean
書寫規範:類的註釋必須寫在該類的宣告語法之前。在註釋中要描述該類的描述,建立者,建立日期。
類註釋模板:可以通過eclipse配置(Code Templates 中的 Code 的New Java files)
${filecomment}
${package_declaration}
/**
* Title: ${project_name}<br>
* Description: <br>
* Copyright: Copyright (c) ${year} <br>
* Create DateTime: ${date} ${time} <br>
* @author perry.li
*/
${typecomment}
${type_declaration}
類註釋示例:
package cn.sh.sstic.projectmanagement.projectfeasibleschemaeval;
/**
* Title: mwbas2008<br>
* Description: 可行性方案套數陣列定義類<br>
* Create DateTime: Oct 6, 2008 4:41:03 PM <br>
* @author perry.li
*/
public class FormUtil {
e)方法的註釋
目的:簡要概述該方法的功能,包括其引數、返回值意義的註釋
範圍:java類中的各種方法
注:介面的實現方法的註釋應寫在介面中而不是實現程式碼中;
對自動生成的get/set方法不需要添加註釋;
如果方法允許null作為引數,或者允許返回值為null,必須在JavaDoc中說明,如果沒有說明,方法的呼叫者不允許使用null作為引數,並認為返回值是null 安全的。
書寫規範:方法註釋必須寫在方法定義之前。該註釋包括:方法其功能的簡單 描述,方法的引數、返回值型別、返回值意義簡單的描述。
模板:對於已定義好的介面的方法,可以直接輸入 /**回車 eclipse可自動生成註釋模板
示例:
/**
* 演示方法註釋
* @param args
* @return
* 返回 null 表示沒有找到
* @throws Exception
*/
private String[] demoFunction(String args) throws Exception{
return null;
}
f)失效程式碼塊的註釋
目的:對一塊暫時不啟用的程式碼進行註釋。
注:這裡並不是指垃圾、無用的程式碼,只是暫時不啟用或暫時不明確的程式碼
書寫規範:失效程式碼塊採用塊註釋方法行註釋方法進行標註。
注:採用註釋塊在 使用eclipse自帶的Format方法(快捷鍵:Ctrl+Shift+F)時需要配置,去掉選中 “Enable block commnet formatting”
示例:
// if (1==1) {
//
// } else {
//
// }
或者
/* if (1 == 1) {
// 如果1與1相等的時候
String code1;
} else {
// 如果1與1不相等的時候
String code2;
}*/
g)分支語句的註釋
目的:簡單描述該分支條件的意義
書寫規範:在分支語句程式碼的下一行進行註釋
示例:
if (1==1) {
//如果1與1相等的時候
code
} else {
//如果1與1不相等的時候
code
}
h)變數、常量的註釋
目的:簡單描述該變數、常量的意義。
書寫規範:變數、常量註釋必須寫在變數、常量定義之前或同一行中,簡單描述其代表的意義。
注:對自迴圈所用的變數(i,j,k,)可以不需要註釋。
示例:
String commitFlag; //提交標誌
i)@Override的使用
所有的重寫方法,在方法開始加上 @Override 關鍵字。
如:
@Override
public void onCreate(Bundle savedInstanceState) {
}
異常處理規範
重新丟擲的異常必須保留原來的異常,即throw new NewException(“message”, e); 而不能寫成throw new NewException(“message”),更不能不繼續往上層丟擲異常。
針對重要的可捕獲的業務相關異常,需建立異常處理類,在方法中捕獲到異常後,反饋到使用者介面上,提示使用者【推薦】
補充規範
程式碼在提交版本控制之前,請確保已清除不必要的log除錯語句
明確的垃圾或無用程式碼必須刪除
安卓開發高階技術交流QQ群:108721298 歡迎入群
微信公眾號:mobilesafehome
(本公眾號支援投票)