不知哪里找到的一個文檔上面的放這上面方便學(xué)習

1. 引言

軟件開發(fā)涉及到各方面人員的交互、協(xié)作，為了有效地進行項目開發(fā)的溝通，完善代碼的維護和交付，有必要在一個小組中采用統(tǒng)一的軟件開發(fā)標準。一般來說，制定這樣的標準有下列好處：

1. 方便軟件維護。據(jù)統(tǒng)計，80％的軟件開發(fā)費用在維護，規(guī)范化的代碼才方便維護，降低維護成本。
2. 在軟件的整個生命期內(nèi)，期望一個編碼人員從開始到該軟件報廢一致維護其代碼是不現(xiàn)實的，必然需要不斷地交付、協(xié)同
3. 好的編碼規(guī)范能夠大大增強代碼的可讀性，便于開發(fā)人員快速的理解新代碼。
4. 任何產(chǎn)品都需要好的包裝。我們可以把代碼本身看作是一種產(chǎn)品，那么按照規(guī)范編程也是對這個“產(chǎn)品”的包裝
5. 規(guī)范化的代碼也是軟件質(zhì)量的保證手段之一，也是軟件過程能夠流暢的基礎(chǔ)。

我們每個人必須牢牢樹立這樣的觀念：你今天所編寫的代碼，會一直使用很多年，并且很有可能被其他人維護和改進。所以，我們必須努力寫出“干凈”和易讀的代碼。

本文檔適用于軟件開發(fā)過程中開發(fā)人員，主要包括編碼人員、測試人員，開發(fā)人員，規(guī)范必須嚴格遵守，否則程序被視為不合格程序。

注：本規(guī)范中標紅的內(nèi)容為強制性遵循內(nèi)容，開發(fā)人員必須遵守。藍色為強烈建議性內(nèi)容，最好遵守，這樣可以避免程序出現(xiàn)一些莫名奇妙的問題。其他內(nèi)容為一般性建議。

2.文件

• 屬性文件后綴為 properties,并且符合 java 中 i18n 的規(guī)范；
• 對于各產(chǎn)品模塊自己的配置文件必須放置在自己模塊的 conf 目錄下；
• 文件的命名需要有一定的意義，盡量簡短，名稱符合操作系統(tǒng)的要求且必須為英文或漢語拼音組成，文件名稱不能存在空格，對于普通的文件單詞與單詞之間采用下滑線進行。

3.命名規(guī)則

3.1 基本的規(guī)則

• 字符集在 26 個英文字母、0 到 9 的阿拉伯數(shù)字和下劃線之中。Java
  中類、字段、方法、變量、常量盡量用字母表達，沒有特別的理由不能用任何的其他字符

• 命名需要有一定的意義，推薦采用問題域中的術(shù)語命名，使命名在一定程度上是自描述的

• 命名盡量的短，如果命名太長，可以采用別名的方式，或者縮寫來簡化命名?？s寫一定要有的意義，而且需要在整個項目中維護這些縮寫的意義

• 名稱縮寫的規(guī)則（對于類名、字段名、變量名稱、模塊名稱等適用）

  1）刪除所有的原音字母，壓縮重復(fù)字母。如 button,縮寫為 btn，
  2）如發(fā)生命名沖突，則在某一縮寫中保留原音。如 batton,為了不與 button 沖突，縮寫為 batn

• 不要用前導(dǎo)下劃線，也不要在命名的末尾用下劃線

3.2 常量命名

• 所有的字符都必須大寫。采用有意義的單詞組合表達，單詞與單詞之間以“_”下劃線隔開。
• 命名盡量簡短，不要超過 16 個字符

程序開發(fā)中最好不要直接對 literal 進行工作，最好引入常量方式應(yīng)用；只有在特別的情況下才能使用， 如在 for 循環(huán)中初始化變量時可直接用-1,0,1 這些常量。

例：

public final int MAX_SIZE = 120;
public final int MAX_WIDTH = 100;
public final String PROPERTY_NAME= "menu" ;

3.3 變量命名

變量的命名包括實例變量，靜態(tài)變量，函數(shù)參數(shù)的命名。

• 避免在命名中采用數(shù)字，除非命名意義明確，程序更加清晰，對實例變量的命名中不應(yīng)該有數(shù)字

• 變量名稱是名詞意義

• 采用有符合問題域意義的單詞或單詞組合。第一個單詞全部小寫，后續(xù)的每個單詞采用首字母大寫，其余小寫(特殊單詞除外，如 URL)

• 命名盡量簡短，不要超過 16 個字符

• 除了生命周期很短的臨時變量外，避免采用單字符作為變量名，實例變量的命名不要用單字符。常用的單字符變量如整型用 i、j、 k、 m、
  n 字符型用 c、d、 e，坐標用 x、y、z。

• 在某些情況下，變量可能需要加上類型前綴，所有的類型前綴必須是小寫，他與變量名稱的實體部分沒有任何間隔，實體部的每個單詞都是首字母大寫，其余字母小寫（特殊單詞除外如
  URL）,類的全局變量強烈建議使用，一般的類型前綴如下：

• 不在特別的情況下，Java 中不推薦采用前綴，而是推薦保持名稱的語義

例：

public int width;
public String fileName;
public static ApplicationContext context;

3.4 方法命名

命名多數(shù)為動詞結(jié)構(gòu)

• 采用有符合問題域意義的單詞或單詞組合。第一個單詞采用小寫，后續(xù)的每個單詞采用首字母大寫，其余小寫（特殊字除外如
  URL），沒有特別理由不用下劃線作為分隔符

• 在 Java 中對屬性方法命名遵循 JavaBean 的標準：
  1） getter 方法：　 get+屬性名, 對 boolean 型采用 is+屬性名，有些特定的屬性名用 has, can 代替 is 可能更好
  2） setter 方法：　 set+屬性名

• 構(gòu)造方法的命名與類名一致

如：

String getName();
string isStopped();
void connect();

3.5 類和接口的命名

• 采用有符合問題域意義的單詞或單詞組合，每個單詞的首字母大寫，其余字母小寫（特殊字除外如 URL）
• 接口的第一個字符采用Ｉ

例：

public class Fiugre
public interface FiugreContainer
public class StdFigure //std為Standard的縮寫

3.6包的命名

• 包名所有的字符都為小寫；
• 兩個不同業(yè)務(wù)的包之間不要雙向依賴,可以單向依賴；
• 采用邏輯上的層次結(jié)構(gòu)，從而減少依賴

4.注釋規(guī)范

4.1 基本規(guī)則

• 注釋應(yīng)該使代碼更加清晰易懂
• 注釋要簡單明了，只要提供能夠明確理解程序所必要的信息就可以了。如果注釋太復(fù)雜說明程序需要修改調(diào)整，使設(shè)計更加合理。
• 注釋不僅描述程序做了什么， 還要描述為什么要這樣做,以及約束
• 對于一般的 getter、setter 方法不用注釋
• 注釋不能嵌套
• 生成開發(fā)文檔的需要用中文編寫

4.2 Java 中有三種注釋方式說明

4.2.1 文檔注釋

可以對用多行，一般用來對類、接口、成員方法、成員變量、靜態(tài)字段、靜態(tài)方法、常量進行說明。Javadoc 可以用它來產(chǎn)生代碼的文檔。為了可讀性，可以有縮進和格式控制。
<p><span><span style="font-family:Verdana, Arial, Helvetica, sans-serif;line-height:19px;text-indent:26px;"><span style="font-size:14px;"><span style="font-family:Arial;line-height:26px;">
</span></span></span></span></p>

文檔注釋常采用一些標簽進行文檔的特定用途描述,用于幫助 Javadoc 產(chǎn)生文檔,常用的有：

4.2.2 行注釋 //

一次只能注釋一行，一般用來簡短的描述某一個局部變量，程序塊的作用。

4.2.3 塊注釋： /* */

在代碼中禁止使用。

4.3 類/接口注釋

類/接口描述，一般比較詳細。按照常用的說明順序排列，主要包括

• 類的主要說明，以?；?結(jié)束
• 類設(shè)計的目標，完成什么樣的功能
• <Strong>主要的類使用</Strong>如何使用該類, 包括環(huán)境要求,如是否線程安全,并發(fā)性要求, 以及使用約束
• <Strong>已知的 BUG</Strong>
• 描述類的修改歷史:<Strong>修改人+日期＋簡單說明</Strong>
• @author 作者、@version 版本, @see 參照,@since 開始版本等信息如：

/** * This class provides default implementations for the JFC <code>Action</code> _ interface. Standard behaviors like the get and set methods for _ <code>Action</code> object properties (icon, text, and enabled) are defined _ here. The developer need only subclass this abstract class and _ define the <code>actionPerformed</code> method. _ <p> _ <strong>Warning:</strong> _ Serialized objects of this class will not be compatible with _ future Swing releases. The current serialization support is appropriate _ for short term storage or RMI between applications running the same _ version of Swing. A future release of Swing will provide support for _ long term persistence. _ _ @version 1.41 02/02/00 _ @author Georges Saab _ @see Action _/

為了使形成的文檔可讀性好，注釋中經(jīng)常帶有縮進和格式控制。類描述放在類的類定義的緊前面，不能有任何的空行。

4.4 變量注釋

• 成員變量、類靜態(tài)變量采用文檔注釋，對成員變量的注釋通常包括：
  1） 變量的意義
  2） 變量的合法值域
  3） 對并發(fā)訪問的限制

如:

/** Web.xml 文件中 configServlet 參數(shù)的 UIAPP.xml initparam **/ 
public final static String APP_CONFIG = "aaa.uiapp";

• 局部變量，如算法相關(guān)的變量采用塊或行注釋

如：

void func() {
    int i; //用于循環(huán)計數(shù)
    …………
}

• 參數(shù)變量注釋一般用文檔注釋,并且用@param 來說明為參數(shù),一般包括:
  1） 參數(shù)的用途
  2） 對參數(shù)值范圍的要求

4.5 方法注釋

描述函數(shù)的功能，對成員方法，靜態(tài)方法一般采用文檔描述，特別是公開的方法。注釋可以很詳細，為了可讀性強也可包含格式控制，如下面說明含有縮進：

/** Here is a method comment with some very special* 
formatting that I want indent(1) to ignore.**/

方法注釋一般包括:

• 方法的主要說明，以?；?結(jié)束

• 描述方法完成什么樣的功能,方法的目標,用該方法的原因

• 描述方法的使用方法,包括使用的環(huán)境要求,如前置條件,后置條件和并發(fā)性要求

• 描述已知的 bug

• 描述方法的修改歷史：<Strong>修改人+日期＋簡單說明</Strong> (<修改人+日期＋簡單說明>)

• @param c elements to be inserted into this list.（參數(shù)說明）

• @return <tt>true</tt> if this list changed as a result of the call.(返回值說明)

• @throws NullPointerException if the specified Collection is null.（異常說明）

• @see 如果重載方法必須參考父類的方法

• Eclips 下采用 Alt+Shift+J 生成 Javadoc 說明方法的放回值((@return)

4.6 修改記錄

? 在修改一個類前，必須先從 SVN 中 update，之后再進行修改；

? 修改的地方必須加入注釋，說明修改人，修改原因，修改內(nèi)容，修改時間；

5.編碼規(guī)范

5.1 基本原則

強制性原則：

• 字符串的拼加操作，必須使用 StringBuilder；

? try…catch 的用法，

try{
 
}catch{Exception e
       e.printStackTrace();
}finally{
 
}//在最外層的Action中可以使用，其它地方一律禁止使用；
 
 
try{
       //程序代碼
}catch(Exception e){
       //為空，什么都不寫
}//在任何場景中都禁止使用
 
 
try{
 
}catch{Exception e
       throw new runtimeException(e)；//最優(yōu)先采用的寫法
}finally{
 
}

• 對于捕獲后，不知道干什么事情或者也不知道怎樣處理的情況，就不要捕獲異常，留給外出層去捕獲處理；
• 返回類型為集合的,在方法聲明中必須使用泛型，必須在 javadoc 中注明什么情況下返回 null，什么情況下返回空集合。
• 對于方法、變量聲明范圍要采用如下優(yōu)先級：private、protected、public，對于變量要采用如下的優(yōu)先級：局部變量、實例變量、類變量，如果必須要采用實例變量或類變量的情況下，要保證線程安全性，如有可能盡量采用
  ThreadLocal 保存實例變量或類變量；
• 如果不是必須，不要在循環(huán)中去定義變量或者 new 對象；盡量在需要的最后一刻才去 new 對象；
• 如果不是必須，不要在循環(huán)中去用 try…catch;
• 類中對于比較復(fù)雜的邏輯要采用行注釋的方式進行注釋，java 代碼中絕對不允許采用塊注釋（/**/）進行注釋；
• Java 類的名稱第一個子母必須大寫，有多個單詞組成的，每個單詞的首字母大寫
• jsp 的文件名必須全部小寫；
• Spring 的 bean 配置文件名必須小寫，格式為 xxx.bean.xml，xxx.bean.xml 配置文件中的<bean
  id=”” ，此處的 id，就是將類名的第一個字母小寫放到此處。
• xwork 的配置文件名必須小寫，且遵循 xwork_xxx.xml 的格式書寫，其中 XXX 是業(yè)務(wù)名稱的縮寫；
• 日志的處理，

if (log.isDebugEnabled())
    ex.printStackTrace();
else
    log.error("從數(shù)據(jù)庫刪除: \[" + entity.getClass().getName() + "\] 實例失敗", daex);
throw new PersistenceException("從數(shù)據(jù)庫刪除: ["+entity.getClass().getName()\+ "\] 實例失敗", daex);

• 代碼中嚴禁使用 System.out.println()進行調(diào)試輸出，如果要使用調(diào)試信息，必須使用
  log.debug()。對于必要的信息使用 log.info()進行輸出；
• 類中不要出現(xiàn)無用 import，可以采用 IDE 工具進行優(yōu)化，類提交前進行代碼的格式化；
• 有業(yè)務(wù)邏輯處理的類必須寫 junit 單元測試類；
• 國際化的支持：ftl 模板中不允許出現(xiàn)中文字符，要全部放到相應(yīng)的 properties 文件中，properties 文件要放到和
  Action 類同樣的目錄中；ftl 的編碼要全部采用 UTF-8 的格式；properties 文件的命名：中文：Action
  名稱+“_zh”+“_CN”.properties，英文：Action 名稱+“_en”+“_US”.properties
• 一個程序文件最好不要超過２０００行
• 盡可能縮小對象的作用域，這樣對象的可見范圍和生存期也都會盡可能地小，盡所有可能優(yōu)先采用局部變量，實在沒有辦法用全局變量的，優(yōu)先采用ThreadLocal 來處理。
• 一個方法所完成的功能要單一,不同的功能封裝為不同的方法.
• 盡可能的處理異?；蜣D(zhuǎn)換異常，不要一味的包裝異常
• 如果對象在某個特定范圍內(nèi)必須被清理（而不是作為垃圾被回收），請使用帶有 finally 子句的 try 塊，在 finally
  子句中進行清理。
• 對于把一些邏輯相關(guān)的類組織在一起，可以考慮把一個類的定義放在另一個類的定義中，這種情況推薦使用內(nèi)部類（比如界面層中的事件響應(yīng)等）。內(nèi)部類擁有所有外圍類所有成員的訪問權(quán)。
• 對成員變量的訪問最好通過 getter/setter 方法,這樣能夠保證訪問的合法性,以及代碼調(diào)整
• 優(yōu)先選擇接口而不是抽象類或具體類。如果你知道某些東西將成為基類，你應(yīng)當優(yōu)先把它們設(shè)計成接口；只有在必須放進方法定義或成員變量時，才把它修改為具體或抽象類。接口只和客戶希望的動作有關(guān)（協(xié)議），而類則傾向于關(guān)注實現(xiàn)細節(jié)。
• 使用 java 標準庫提供的容器。精通他們的用法，將極大地提高工作效率。優(yōu)先選擇 ArrayList 來處理順序結(jié)構(gòu)，選擇 HashSet 來處理集合，選擇 HashMap 來處理關(guān)聯(lián)數(shù)組，選擇 linkedList 來處理堆棧和隊列，它對順序訪問進行了優(yōu)化，向List 中間插入與刪除的開銷小，但隨機訪問則較慢。當使用前三個的時候，應(yīng)該把他們向上轉(zhuǎn)型為 List、Set 和Map,這樣就可以在必要的時候以其它方式實現(xiàn)
• 數(shù)組是一種效率最高的存儲和隨機訪問對象引用序列的方式，但是當創(chuàng)建了一個數(shù)組對象，數(shù)組的大小就被固定了，如果在空間不足時再創(chuàng)建新的數(shù)組進行復(fù)制，這樣效率就比ArrayList 開銷大了。所以必須明確使用場景。
• 盡量使用”private”、”protected”關(guān)鍵字。一旦你把庫的特征（包括類、方法、字段）標記為public,你就再也不可能去掉他們。在這種方式下，實現(xiàn)的變動對派生類造成的影響最小，在處理多線程問題的時候，保持私有性尤其重要，因為只有Private 的字段才會受到保護，而不用擔心被未受同步控制的使用所破壞。
• 禁止后臺業(yè)務(wù)代碼使用如下代碼

try{
    something()
}catch(Exception ex)
{}
new Exception()

5.2 類編寫規(guī)范

類的結(jié)構(gòu)組織，一般按照如下的順序：

1． 常量聲明

2． 靜態(tài)變量聲明

3． 成員變量聲明

4． 構(gòu)造函數(shù)部分

5． Finalize 部分

6． 成員方法部分

7． 靜態(tài)方法部分

這種順序是推薦的，在實際開發(fā)中可以按照一定的尺度修改，原則是程序更易讀。如對方法的排序按照重要性，或按照字母順序排列或按照方法之間的關(guān)系排列。

每個方法（包括構(gòu)造與 finalize）都是一個段。多個變量聲明按照邏輯共同組成一個段，段與段之間以空行分隔。

類聲明時，要指出其訪問控制，一般為沒有修飾符，public，和 private。

方法與方法之間，大的部分之間都需要以空行隔離。

編寫通用性的類時，請遵守標準形式。包括定義 equals()、hasCode()、toString()、Clone(實現(xiàn) Cloneable 接口)，并實現(xiàn) Comparable 和 Serialiable 接口

對于設(shè)計期間不需要繼承的類，盡量使用 final

5.3 變量

• 對成員變量, 盡量采用 private
• 每一個變量聲明/定義占一行（參數(shù)變量除外），如：

int a;
int b;

比 int a,b; 更容易讀, 更容易查找 bug

• 局部變量在使用前必須初始化，一般在聲明時初始化
• 變量的聲明要放在程序塊的開始位置

如：

void myMethod() {
    int int1 = 0; // beginning of method block
    if (condition) {
        int int2 = 0; // beginning of "if" block
        ...
    }
}

一種例外情況是在 for 語句中，定義聲明不僅不占一行，還在表達式內(nèi)部，完全采用 Eclips 生成,如：

for(int i = 0; i<100; i++)

• 數(shù)組的申明采用 <數(shù)據(jù)類型[] + 變量名>方式如：

char[] buffer;

而不是：

char buffer[];

5.4 方法

? 對成員方法,不要輕易的采用 public 的成員變量。主要的修飾符有 public, private, protected, 無

? 空方法中方法聲明和函數(shù)體可都在一行。如：　 void func(){}

? 方法和方法之間空一行

? 方法的文檔注釋放在方法的緊前面，不能空一行。

? 避免過多的參數(shù)列表，盡量控制在５個以內(nèi)，若需要傳遞多個參數(shù)時，當使用一個容納這些參數(shù)的對象進行傳遞，以提高程序的可讀性和可擴展性

? 方法中的循環(huán)潛套不能超過２層

? 對于設(shè)計期間不需要子類來重載的類，盡量使用 final

? 每個方法盡量代碼行數(shù)盡量不要超過 100 行（有效代碼行，不包括注釋），但必須保證邏輯的完整性

? 接口中的方法默認級別為 protected，只有很確認其它子系統(tǒng)的包會調(diào)用自己子系統(tǒng)的接口中的方法時，才將方法暴露為 public.

5.5 語言使用及書寫規(guī)范

• 避免變量的定義與上一層作用域的變量同名。
• 方法與方法之間用需要用一空行隔開
• 局部變量在使用時刻聲明，局部變量/靜態(tài)變量在聲明時同時初始化
• 在與常數(shù)作比較時常數(shù)放在比較表達式的前面如：

if(“simpleCase”.equals(obj))
    …
if(null == obj)
    ….

• return 語句中，不要有復(fù)雜的運算。

• switch 語句，需要一個缺省的分支

6.框架相關(guān)規(guī)范

Spring 配置文件中定義 bean 時，id 或者 name 屬性值的第一個單詞首字母必須小寫，且必須與 java 代碼中聲明的變量相同。xwork 配置文件中定義 action 的 name 時，第一個單詞首字母也必須要小寫。

在 spring bean 或 action 的配置文件中聲明的屬性，在 java 代碼中對應(yīng)的屬性必須要有 getter 和 setter 方法。