電信事業(yè)部Java編程規(guī)范

1、電信事業(yè)部Java項(xiàng)目編程規(guī)范版本 <1.0> _ 修訂歷史記錄日期版本說明作者<27日/10月/2008年><0.6>初步擬定田標(biāo)<1日/11月/2008年><0.8>楊濟(jì)嘉<10日/11月/2008年><0.8>補(bǔ)充錯誤處理和異常處理事件部分的內(nèi)容田標(biāo)目錄1.簡介61.1目的61.2范圍61.3定義、首字母縮寫詞和縮略語61.4參考資料61.5概述62.代碼組織與風(fēng)格72.1開頭注釋72.2包和引入語句72.3類的注釋72.4類聲明72.5類的成員變量72.6構(gòu)造函數(shù)82.7類方法82.8關(guān)于代碼組織與風(fēng)格

2、的推薦示例93.縮進(jìn)排版163.1行長度163.2換行164.注釋164.1類的注釋164.2方法的注釋174.3類屬性的注釋174.4非JavaDoc的注釋185.命名185.1包的命名185.2類的命名185.3接口的命名185.4方法的命名185.5變量的命名185.6Final變量（常量）的命名185.7參數(shù)的命名186.聲明186.1每行聲明變量的數(shù)量186.2初始化186.3避免覆蓋186.4數(shù)組的聲明186.5類和接口的聲明197.表達(dá)式和語句197.1簡單語句197.2復(fù)合語句197.3選擇和循環(huán)語句197.4switch-case語句207.5try-catch/try-ca

3、tch-finally語句208.空白208.1空行218.2空格219.設(shè)計類和方法219.1創(chuàng)建具有很強(qiáng)內(nèi)聚力的類219.2創(chuàng)建松散連接和高度專用的方法219.2.1使所有方法都執(zhí)行專門的任務(wù)219.2.2盡量使方法成為自成一體的獨(dú)立方法229.2.3設(shè)計類和方法時，要達(dá)到下列目的229.3編程原則229.3.1為方法和類賦予表義性強(qiáng)的名字229.3.2為每個方法賦予單個退出點(diǎn)239.3.3創(chuàng)建方法時，始終都應(yīng)顯式地定義它的作用域。239.3.4用參數(shù)在方法之間傳遞數(shù)據(jù)2310.一些編程慣例2310.1提供對實(shí)例以及類變量的訪問控制2310.2引用類變量和類方法2310.3常量2310.4

4、變量賦值2310.5圓括號2311.內(nèi)存管理2312.錯誤處理和異常事件2312.1錯誤捕獲方式：2412.1.1FATAL級別的例外：2412.1.2其他級別的例外：2412.1.3釋放資源統(tǒng)一在final里面做.2412.2錯誤日志處理：2412.2.1FATAL級別：2412.2.2ERROR級別：2412.2.3WARN級別：2412.2.4INFO級別：2412.2.5DEBUG級別：2413.可移植性2414.復(fù)用2515.涉及到代碼質(zhì)量的問題2515.1制造多余代碼2515.2質(zhì)量上有缺陷的代碼2615.3很多小技巧3115.4致命的問題3416.編譯問題3517.附錄：指南概要

5、35Java項(xiàng)目編程指南1. 簡介此編程指南的文檔用來規(guī)范每一個一線開發(fā)人員代碼的編寫，試圖確保代碼編寫的規(guī)范化和代碼編寫的質(zhì)量，進(jìn)而提高我們開發(fā)的項(xiàng)目的質(zhì)量和開發(fā)團(tuán)隊(duì)的編碼水平。此編程指南的內(nèi)容涵蓋了從源代碼文件的結(jié)構(gòu)、格式，對常見代碼要素的格式和內(nèi)容兩個方面的要求，到如何避免長犯的錯誤，避免bug、如何提高代碼的嚴(yán)謹(jǐn)性、可靠性和提高質(zhì)量等方方面面的內(nèi)容，需要每一個開發(fā)人員在每天的工作中嚴(yán)格遵守。1.1 目的Ø 提高編碼工作的規(guī)范性Ø 提高完成的代碼的規(guī)范性Ø 避免編寫多余、低效、漏洞百出的代碼Ø 加強(qiáng)開發(fā)人員的技術(shù)素養(yǎng)、提高開發(fā)工作的質(zhì)量1.2 范圍

6、這個文檔的范圍包括：Ø 一個源代碼文件的內(nèi)容，應(yīng)該怎樣組織，風(fēng)格怎樣Ø 代碼中注釋的位置、寫法、要求Ø 包、類、方法、常量、變量、屬性等的命名的要求Ø 聲明的編寫要求Ø 表達(dá)式的編寫要求Ø 內(nèi)存管理方面的要求Ø 異常處理方面的要求Ø 針對可移植性的編程要求Ø 針對復(fù)用的編程要求Ø這些要求對于提高代碼質(zhì)量、提高代碼的規(guī)范性有幫助，定義這個規(guī)范的目的是讓項(xiàng)目中所有的文檔都看起來像一個人寫的，增加可讀性，減少項(xiàng)目組中因?yàn)槿藛T變更而帶來的損失。這些規(guī)范并不是一定要絕對遵守，但是一定要讓程序有良好的可讀性

7、，需要各開發(fā)同事努力遵守。1.3 定義、首字母縮寫詞和縮略語本小節(jié)應(yīng)提供正確理解此編程指南所需的全部術(shù)語、首字母縮寫詞和縮略語的定義。這些信息可以通過引用項(xiàng)目詞匯表來提供。1.4 參考資料Sun公司制定的Java編程規(guī)范一些基礎(chǔ)Java庫，包括JDK、Spring、Apache的一些開業(yè)項(xiàng)目的代碼編寫方式1.5 概述文檔中接下來的內(nèi)容首先闡述了關(guān)于代碼的組織和風(fēng)格有關(guān)的建議，接下來闡述了圍繞編寫高效率、可移植性、錯誤處理等論題的一些建議。2. 代碼組織與風(fēng)格每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關(guān)聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件

8、中的第一個類或接口。Java源文件的組織如下：2.1 開頭注釋所有的源文件都應(yīng)該在開頭有一個C語言風(fēng)格的注釋，其中列出類名、版本信息、日期和版權(quán)聲明：/* * Classname * * Version information * * Date * * Copyright notice */2.2 包和引入語句package 行要在 import 行之前，兩者之間以空行分隔。import 中標(biāo)準(zhǔn)的包名要在本地的包名之前，而且按照字母順序排列。（在Eclipse中，可以用快捷鍵Ctrl+Shift+O來導(dǎo)入需要的類和清除該類不需要的import語句。）package .stats;import

9、java.io.*;import java.util.Observable;import hotlava.util.Application;2.3 類的注釋接下來的是類的注釋，一般用來解釋類的作用，形式如下：/* * A class representing a set of packet and byte counters * It is observable to allow it to be watched, but only * reports changes when the current set is complete */2.4 類聲明包括類的訪問修飾符、類名、繼承的父類、實(shí)現(xiàn)

10、的接口等。2.5 類的成員變量建議以下面先后順序組織類成員變量：a. 靜態(tài)變量(static)：首先是類的公共變量(public)，隨后是保護(hù)變量(protected)，再后是包一級別的變量(沒有訪問修飾符)，最后是私有變量(private)。b. 實(shí)例變量：首先是類的公共變量(public)，隨后是保護(hù)變量(protected)，再后是包一級別的變量(沒有訪問修飾符)，最后是私有變量(private)。一般情況下，不鼓勵以public的方式定義類的實(shí)例變量，對類的實(shí)例變量的操作應(yīng)該通過類的方法，比如getter和setter來進(jìn)行。public的成員變量必須生成文檔(JavaDoc)。pro

11、ceted、private和package定義的成員變量如果名字含義明確的話，可以沒有注釋。/* * Packet counters */protected int packets;2.6 構(gòu)造函數(shù)構(gòu)造函數(shù)應(yīng)該用遞增的方式寫(比如:參數(shù)多的寫在后面)。2.7 類方法靜態(tài)方法一般放在最前面。類方法應(yīng)該按功能，而非作用域或訪問權(quán)限，分組。例如，一個私有的類方法可以置于兩個公有的實(shí)例方法之間。其目的是為了更便于閱讀和理解代碼。/* * Set the packet counters (such as when restoring from a database). * * param r1 * pa

12、ram r2 * param r3 * param r4 * throws IllegalArgumentException */protected final void setArray(int r1, int r2, int r3, int r4)throws IllegalArgumentException / Ensure the arrays are of equal sizeif (r1.length != r2.length | r1.length != r3.length| r1.length != r4.length)throw new IllegalArgumentExce

13、ption("Arrays must be of the same size");System.arraycopy(r1, 0, r3, 0, r1.length);System.arraycopy(r2, 0, r4, 0, r1.length);下面JDK中NullPointerException這個類的源代碼，是一個很好的示例：/* * (#)NullPointerException.java1.20 05/11/17 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRI

14、ETARY/CONFIDENTIAL. Use is subject to license terms. */package java.lang;/* * Thrown when an application attempts to use <code>null</code> in a * case where an object is required. These include: * <ul> * <li>Calling the instance method of a <code>null</code> objec

15、t. * <li>Accessing or modifying the field of a <code>null</code> object. * <li>Taking the length of <code>null</code> as if it were an array. * <li>Accessing or modifying the slots of <code>null</code> as if it * were an array. * <li>Throwi

16、ng <code>null</code> as if it were a <code>Throwable</code> * value. * </ul> * <p> * Applications should throw instances of this class to indicate * other illegal uses of the <code>null</code> object. * * author unascribed * version 1.20, 11/17/05 * si

17、nce JDK1.0 */public class NullPointerException extends RuntimeException /* * Constructs a <code>NullPointerException</code> with no detail message. */public NullPointerException() super();/* * Constructs a <code>NullPointerException</code> with the specified * detail message.

18、 * * param s the detail message. */public NullPointerException(String s) super(s);2.8 關(guān)于代碼組織與風(fēng)格的推薦示例上面說了這么多，下面以M2M項(xiàng)目中使用的一個實(shí)際的class的源代碼來說明，我們的代碼必須達(dá)到的基本水平，如下：/* * (#)UserDetailsServiceImpl.java1.0 2008-10-24 * * Copyright 2004-2008 廣州市聚暉電子有限公司, Inc. All rights reserved. * Tri-sun PROPRIETARY/CONFIDENT

19、IAL. Use is subject to license terms. */package com.trisun.m2m.security;import java.util.Iterator;import java.util.List;import org.acegisecurity.GrantedAuthority;import org.acegisecurity.GrantedAuthorityImpl;import org.acegisecurity.userdetails.User;import org.acegisecurity.userdetails.UserDetails;i

20、mport org.acegisecurity.userdetails.UserDetailsService;import org.acegisecurity.userdetails.UsernameNotFoundException;import org.springframework.dao.DataAccessException;import mons.lang.StringUtils;import mon.utils.Obfuscator;import com.trisun.m2m.enums.UserKind;import com.trisun.m2m.hibernate.Busin

21、essOperatorManagerImpl;import com.trisun.m2m.hibernate.CustomerManagerImpl;import com.trisun.m2m.hibernate.ManufacturerOperatorManagerImpl;import com.trisun.m2m.hibernate.OperatorManagerImpl;import com.trisun.m2m.model.BusinessOperator;import com.trisun.m2m.model.Customer;import com.trisun.m2m.model

22、.ManufacturerOperator;import com.trisun.m2m.model.Operator;import com.trisun.m2m.model.Roles;/* * 實(shí)現(xiàn)了Acegi框架的UserDetailService接口，用于在數(shù)據(jù)庫中根據(jù)用戶名查找用戶，<br> * 并封裝為Acegi框架的UserDetails對象返回給框架。 * * author 楊濟(jì)嘉 */public class UserDetailsServiceImpl implements UserDetailsService /* * 客戶的GrantedAuthority對象

23、 */ private final GrantedAuthority ROLE_CUSTOMER = new GrantedAuthorityImpl( "ROLE_CUSTOMER"); /* * 運(yùn)營商操作員的GrantedAuthority對象 */ private final GrantedAuthority ROLE_OPERATOR = new GrantedAuthorityImpl( "ROLE_OPERATOR"); /* * 業(yè)務(wù)操作員的GrantedAuthority對象 */ private final GrantedAuthor

24、ity ROLE_BUSINESSOPERATOR = new GrantedAuthorityImpl( "ROLE_BUSINESSOPERATOR"); /* * 終端廠商操作員的GrantedAuthority對象 */ private final GrantedAuthority ROLE_MANUFACTUREROPERATOR = new GrantedAuthorityImpl( "ROLE_MANUFACTUREROPERATOR"); /* * 客戶DAO */ private CustomerManagerImpl customer

25、ManagerImpl; /* * 運(yùn)營商操作員DAO */ private OperatorManagerImpl operatorManagerImp; /* * 業(yè)務(wù)操作員DAO */ private BusinessOperatorManagerImpl businessOperatorManager; /* * 終端廠商操作員DAO */ private ManufacturerOperatorManagerImpl manufacturerOperatorManager; /* * 根據(jù)用戶名查找用戶并封裝為UserDetails對象返回。 * * param username 用

26、戶名 * return 存有用戶信息的UserDetails對象 * throws UsernameNotFoundException 找不到輸入的用戶名時拋出這個異常 * throws DataAccessException 訪問數(shù)據(jù)庫出錯時拋出這個異常 */ public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException if(StringUtils.isBlank(username) return null; / 獲取用戶類型 User

27、Kind userKind = UserKindContext.getContext().getUserKind(); / 根據(jù)不同類型用戶查找用戶 switch (userKind) case CUSTOMER: return loadCustomerByUsername(username); case OPERATOR: return loadOperatorByUsername(username); case BUSINESS_OPERATOR: return loadBusinessOperatorByUsername(username); case MANUFACTURER_OPER

28、ATOR: return loadManufacturerOperatorByUsername(username); default: return null; /* * 查找客戶。 * * param username 用戶名 * return 存有客戶信息的UserDetails對象 * throws UsernameNotFoundException 找不到輸入的用戶名時拋出這個異常 * throws DataAccessException 訪問數(shù)據(jù)庫出錯時拋出這個異常 */ SuppressWarnings("unchecked") private UserDeta

29、ils loadCustomerByUsername(String username) throws UsernameNotFoundException, DataAccessException List<Customer> customers = customerManagerImpl.find("from Customer c where c.phoneNum=?", username); String password; if (customers = null | customers.isEmpty() throw new UsernameNotFoun

30、dException("Customer '" + username + "' not found"); try password = Obfuscator.deobfuscate(customers.get(0).getPassword(); catch (RuntimeException e) throw new UsernameNotFoundException("Password of customer '" + username + "' is wrong"); Grant

31、edAuthority authors = new GrantedAuthorityROLE_CUSTOMER; return new User(username, password, true, true, true, true, authors); /* * 查找運(yùn)營商操作員。 * * param username 用戶名 * return 存有運(yùn)營商操作員信息的UserDetails對象 * throws UsernameNotFoundException 找不到輸入的用戶名時拋出這個異常 * throws DataAccessException 訪問數(shù)據(jù)庫出錯時拋出這個異常 */ Su

32、ppressWarnings("unchecked") private UserDetails loadOperatorByUsername(String username) throws UsernameNotFoundException, DataAccessException List<Operator> operators = operatorManagerImp.find("from Operator o where o.account=?", username); if (operators = null | operators.

33、isEmpty() throw new UsernameNotFoundException("Operator '" + username + "' not found"); String password; try password = Obfuscator.deobfuscate(operators.get(0).getPassword(); catch (RuntimeException e) throw new UsernameNotFoundException("Password of operator '&q

34、uot; + username + "' is wrong"); java.util.Collection<Roles> roles = operators.get(0).getRoleList(); int size = roles.size(); GrantedAuthority authors = new GrantedAuthoritysize + 1; authors0 = ROLE_OPERATOR; Iterator<Roles> role = roles.iterator(); Roles rs; int i = 1; whi

35、le (role.hasNext() rs = role.next(); authorsi = new GrantedAuthorityImpl(rs.getRoleName(); i+; return new User(username, password, true, true, true, true, authors); /* * 查找業(yè)務(wù)操作員。 * * param username 用戶名 * return 存有業(yè)務(wù)操作員信息的UserDetails對象 * throws UsernameNotFoundException 找不到輸入的用戶名時拋出這個異常 * throws Data

36、AccessException 訪問數(shù)據(jù)庫出錯時拋出這個異常 */ SuppressWarnings("unchecked") private UserDetails loadBusinessOperatorByUsername(String username) throws UsernameNotFoundException, DataAccessException List<BusinessOperator> businessOperators = businessOperatorManager .find("from BusinessOperat

37、or b where b.account=?", username); if (businessOperators = null | businessOperators.isEmpty() throw new UsernameNotFoundException("Business Operator '" + username + "' not found"); String password; try password = Obfuscator.deobfuscate(businessOperators.get(0) .getP

38、assword(); catch (RuntimeException e) throw new UsernameNotFoundException( "Password of business Operator '" + username + "' is wrong"); GrantedAuthority authors = new GrantedAuthorityROLE_BUSINESSOPERATOR; return new User(username, password, true, true, true, true, autho

39、rs); /* * 查找終端廠商操作員。 * * param username 用戶名 * return 存有終端廠商操作員信息的UserDetails對象 * throws UsernameNotFoundException 找不到輸入的用戶名時拋出這個異常 * throws DataAccessException 訪問數(shù)據(jù)庫出錯時拋出這個異常 */ SuppressWarnings("unchecked") private UserDetails loadManufacturerOperatorByUsername(String username) throws Use

40、rnameNotFoundException, DataAccessException List<ManufacturerOperator> manufacturerOperators = manufacturerOperatorManager .find("from ManufacturerOperator mo where mo.account=?", username); if (manufacturerOperators = null | manufacturerOperators.isEmpty() throw new UsernameNotFound

41、Exception("Manufacturer Operator '" + username + "' not found"); String password; try password = Obfuscator.deobfuscate(manufacturerOperators.get(0) .getPassword(); catch (RuntimeException e) throw new UsernameNotFoundException( "Password of manufacturer Operator 

42、9;" + username + "' is wrong"); GrantedAuthority authors = new GrantedAuthorityROLE_MANUFACTUREROPERATOR; return new User(username, password, true, true, true, true, authors); / getter & setter public CustomerManagerImpl getCustomerManagerImpl() return customerManagerImpl; pub

43、lic void setCustomerManagerImpl(CustomerManagerImpl customerManagerImpl) this.customerManagerImpl = customerManagerImpl; if (null != customerManagerImpl) this.customerManagerImpl.getHibernateTemplate().setCacheQueries(true); public OperatorManagerImpl getOperatorManagerImp() return operatorManagerIm

44、p; public void setOperatorManagerImp(OperatorManagerImpl operatorManagerImp) this.operatorManagerImp = operatorManagerImp; if (null != operatorManagerImp) this.operatorManagerImp.getHibernateTemplate().setCacheQueries(true); public BusinessOperatorManagerImpl getBusinessOperatorManager() return busi

45、nessOperatorManager; public void setBusinessOperatorManager( BusinessOperatorManagerImpl businessOperatorManager) this.businessOperatorManager = businessOperatorManager; if (null != businessOperatorManager) this.businessOperatorManager.getHibernateTemplate().setCacheQueries(true); public Manufacture

46、rOperatorManagerImpl getManufacturerOperatorManager() return manufacturerOperatorManager; public void setManufacturerOperatorManager( ManufacturerOperatorManagerImpl manufacturerOperatorManager) this.manufacturerOperatorManager = manufacturerOperatorManager; if (null != manufacturerOperatorManager)

47、this.manufacturerOperatorManager.getHibernateTemplate().setCacheQueries(true); 基本要求：Ø 類必須包含至少含有如下內(nèi)容的源代碼版權(quán)聲明：/* * (#)UserDetailsServiceImpl.java1.0 2008-10-24 * * Copyright 2004-2008 廣州市聚暉電子有限公司, Inc. All rights reserved. * Tri-sun PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */

48、16; 類的注釋必須具備，格式如上所述，要盡量說明類的作用，為什么使用它、相關(guān)的調(diào)用關(guān)系以及其它必須說明的問題。Ø 屬性的說明必須基本，格式如上所述。Ø 方法的說明必須基本，格式如上所述。Ø 方法的參數(shù)的意義、返回值的意義以及有關(guān)的需要注意的問題，必須說明。3. 縮進(jìn)排版代碼因適當(dāng)使用縮進(jìn)排版提高可讀性，一般使用1個制表符（Tab）作為縮進(jìn)單位。3.1 行長度盡量避免一行的長度超過80個字符，因?yàn)楹芏嘟K端和工具不能很好處理。3.2 換行當(dāng)一個表達(dá)式無法容納在一行內(nèi)時，可以依據(jù)如下一般規(guī)則斷開之：- 在一個逗號后面斷開- 在一個操作符前面斷開- 寧可選擇較高級別(h

49、igher-level)的斷開，而非較低級別(lower-level)的斷開- 新的一行應(yīng)該與上一行同一級別表達(dá)式的開頭處對齊- 如果以上規(guī)則導(dǎo)致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進(jìn)2個制表符（Tab）。 4. 注釋按照下面方式編寫注釋后，可以很容易生成我們編寫的源代碼的說明文檔，生成后的文檔形式如下，可以方便代碼的維護(hù)，是目前所有Java開發(fā)的項(xiàng)目的通用形式：例如，上面類NullPointerException的Java Doc文檔的一部分如下，我們可以很容易地看出和上面的示例中類的注釋部分一一對應(yīng)情況：4.1 類的注釋在類名所在行的上方輸入字符“/*”，如下圖所示：然后在

50、下圖中，選中的行的位置添加類的注釋，說明類的作用、調(diào)用關(guān)系，要注意的問題等。4.2 方法的注釋在方法上面輸入字符“/*”，如下圖所示：然后回車，效果如下圖：接下來在被選中的那一行上添加注釋就可以了，return部分描述了方法的返回值，也需要用注釋說明。4.3 類屬性的注釋類屬性的注釋的添加方式和上面提到的類、方法的注釋的添加方式一樣，正確添加后的效果如下：下面的方式是錯誤的，只能通過開代碼看到：4.4 非JavaDoc的注釋 如果方法中的算法或者業(yè)務(wù)邏輯比較復(fù)雜，除了在方法前使用JavaDoc注釋之外，在方法體內(nèi)也應(yīng)適當(dāng)使用非JavaDoc的注釋解釋清楚方法的實(shí)現(xiàn)思路和流程。這些注釋可以選擇使用“/* . */”或者是“/ .”的形式。5. 命名包、類、方法、屬性、變量等的命名對于代碼的維護(hù)有重要的意義，胡亂命名的代碼很容易變成對自己和別人的工作都不利的事情。命名規(guī)范使程序更易讀，從而更易于理解。它們也可以提供一些有關(guān)標(biāo)識符功能的信息，以助于理解代碼。5.1 包的命名包的名字應(yīng)該全部小寫的ASCII字母組成。5.2 類的命名類名是一個名詞，采用大小寫混合的方式，每個單詞的首字母大寫。盡量使你的類名簡潔而富于描述。使用完整單詞，避免縮寫詞(除非該縮寫詞被更廣泛使用，像URL，HTML)。5.3 接口的命名大小寫規(guī)則與類相同。5.4 方法的命名 方法名是一