騰訊編碼規(guī)范

GL/YF 013-2007V1.0-L1騰訊集團(tuán)管理標(biāo)準(zhǔn) GL/YF 013-2007V1.0-L1Java編碼規(guī)范2007-09-11發(fā)布 2007-09-11實(shí)施騰訊集團(tuán) 發(fā)布18前 言本標(biāo)準(zhǔn)系公司首次發(fā)布實(shí)施，主要針對(duì)公司所有軟件產(chǎn)品源代碼范圍的Java編碼風(fēng)格，對(duì)Java文件的文件組織、代碼風(fēng)格、注釋、命名、聲明、異常、習(xí)慣等方面均作出規(guī)范，以保障公司項(xiàng)目代碼的易維護(hù)性和編碼安全性。本標(biāo)準(zhǔn)由研發(fā)管理部、3G產(chǎn)品中心共同制定。本標(biāo)準(zhǔn)主要起草人：Junjun(張莉珺)、Iron（邱會(huì)發(fā)） 本標(biāo)準(zhǔn)主要審核人：anwenfeng(馮文信)、 Paulinesong(宋虹漫)、Ericlin（林松）、Stevezheng(鄭全戰(zhàn)) 、Junehuang(黃俊)、Kevinxu(許冠嚴(yán))、polo(陳廣域)、leon（郭凱天）本標(biāo)準(zhǔn)批準(zhǔn)人：jeffxiong(熊明華) 、charles(陳一丹)、tony（張志東）、ponyma（馬化騰）本標(biāo)準(zhǔn)首次發(fā)布日期：2007年9月11日本標(biāo)準(zhǔn)發(fā)送部門：公司各部門JAVA編碼規(guī)范1 目的為形成公司統(tǒng)一的Java編碼風(fēng)格，以保障公司項(xiàng)目代碼的易維護(hù)性和編碼安全性，特制定本規(guī)范。2 適用范圍本標(biāo)準(zhǔn)適用于騰訊集團(tuán)（含分公司等各級(jí)分支機(jī)構(gòu)）所有使用Java作為開(kāi)發(fā)語(yǔ)言的軟件產(chǎn)品。本標(biāo)準(zhǔn)中“騰訊集團(tuán)”是指騰訊控股有限公司、其附屬公司、及為會(huì)計(jì)而綜合入賬的公司，包括但不限于騰訊控股有限公司、深圳市騰訊計(jì)算機(jī)系統(tǒng)有限公司、騰訊科技（深圳）有限公司、騰訊科技（北京）有限公司、深圳市世紀(jì)凱旋科技有限公司、時(shí)代朝陽(yáng)科技（深圳）有限公司、騰訊數(shù)碼（深圳）有限公司、深圳市財(cái)付通科技有限公司。3 總體原則所有使用Java作為開(kāi)發(fā)語(yǔ)言的軟件產(chǎn)品都須遵照本規(guī)范的內(nèi)容進(jìn)行編碼。4 文件組織4.1 規(guī)則4.1.1由于超過(guò)2000行的程序難以閱讀，應(yīng)該盡量避免出現(xiàn)超過(guò)2000行的程序；4.1.2一個(gè)Java源文件都包含一個(gè)單一的公共類或接口。若私有類和接口與一個(gè)公共類相關(guān)聯(lián)，可以將它們和公共類放入同一個(gè)源文件。公共類必須是這個(gè)文件中的第一個(gè)類或接口。4.2 組織順序4.2.1文件注釋（參見(jiàn)6.1文件注釋）；4.2.2包和引入語(yǔ)句：在多數(shù)Java源文件中，第一個(gè)非注釋行是包語(yǔ)句。在它之后可以跟引入語(yǔ)句；4.2.3類或接口注釋（參見(jiàn)6.2類或接口注釋）；4.2.4類或接口的聲明；4.2.5類或接口的實(shí)現(xiàn)注釋：如果有關(guān)類或接口的信息不適合作為“類或接口文檔注釋”，可以在類或接口的實(shí)現(xiàn)注釋中給出；4.2.6類的（靜態(tài)）變量：首先是類的公共變量，隨后是保護(hù)變量，再后是包一級(jí)別的變量（沒(méi)有訪問(wèn)修飾符），最后是私有變量；4.2.7實(shí)例變量：首先是公共級(jí)別的，隨后是保護(hù)級(jí)別的，再后是包一級(jí)別的（沒(méi)有訪問(wèn)修飾符），最后是私有級(jí)別的；4.2.8構(gòu)造方法；4.2.9方法：方法應(yīng)該按功能分組，而不應(yīng)該按作用域或訪問(wèn)權(quán)限進(jìn)行分組。4.3 范例直接查看以下文件可以找到編碼套用的規(guī)則：（注：可以通過(guò)復(fù)制粘貼保存到硬盤）5 代碼風(fēng)格5.1 縮進(jìn)5.1.1程序塊要采用縮進(jìn)風(fēng)格編寫，縮進(jìn)只使用TAB鍵，不能使用空格鍵（編輯器中請(qǐng)將TAB設(shè)置為4格）；5.1.2方法體的開(kāi)始、類的定義、以及if、for、do、while、switch、case語(yǔ)句中的代碼都要采用縮進(jìn)方式；5.2 對(duì)齊5.2.1程序塊的分界符左大括號(hào) 和右大括號(hào)都另起一行，應(yīng)各獨(dú)占一行并且位于同一列，同時(shí)與引用它們的語(yǔ)句左對(duì)齊；5.2.2對(duì)齊只使用TAB鍵，不使用空格鍵；5.2.3不允許把多個(gè)短語(yǔ)句寫在一行中，即一行只寫一條語(yǔ)句；5.2.4 if、for、do、while、case、switch、default等語(yǔ)句自占一行。5.3 換行一行的長(zhǎng)度超過(guò)80個(gè)字符需要換行，換行規(guī)則如下：5.3.1在一個(gè)逗號(hào)后面斷開(kāi)；5.3.2在一個(gè)操作符前面斷開(kāi)；5.3.3長(zhǎng)表達(dá)式要在低優(yōu)先級(jí)操作符處劃分新行；5.3.4新行縮進(jìn)2個(gè)TAB。5.4 間隔5.4.1類、方法及相對(duì)獨(dú)立的程序塊之間、變量說(shuō)明之后必須加空行；5.4.2關(guān)鍵字之后要留空格， 象if、for、while 等關(guān)鍵字之后應(yīng)留一個(gè)空格再跟左括號(hào)（， 以突出關(guān)鍵字；5.4.3方法名與其左括號(hào)（之間不要留空格, 以與關(guān)鍵字區(qū)別；5.4.4二元操作符如 =、 += =、 =、 +、 *、 %、 &、 |、 1)int isShow = 0;/ 是否顯示6.5.2多行注釋使用注釋界定符/*.*/，例如： /* * Here is a block comment with * multiple lines for text comments. */7 命名7.1 基本規(guī)則7.1.1使用可以準(zhǔn)確說(shuō)明變量、字段、類、接口、包等完整的英文描述符；7.1.2采用大小寫混合，提高名字的可讀性；7.1.3采用該領(lǐng)域的術(shù)語(yǔ)；盡量少用縮寫，但如果一定要使用，當(dāng)使用公共縮寫和習(xí)慣縮寫等；7.1.4避免使用相似或者僅在大小寫上有區(qū)別的名字。7.2 包命名7.2.1包名一律小寫, 少用縮寫和長(zhǎng)名；7.2.2采用以下規(guī)則：基本包.項(xiàng)目名.模塊名.子模塊名.7.2.3基本包：com.tencent 或 com.qq；7.2.4不得將類直接定義在基本包下，所有項(xiàng)目中的類、接口等都應(yīng)當(dāng)定義在各自的項(xiàng)目和模塊包中；例如：package com.tencent.kqq;package com.tencent.kqq.util;7.3 類或接口命名類或接口名是個(gè)一名詞，采用大小寫混合的方式，每個(gè)單詞的首字母大寫。盡量使你的類名簡(jiǎn)潔而富于描述。使用完整單詞，避免用縮寫詞(除非該縮寫詞被更廣泛使用，像URL，HTML)。例如：class Raster;class ImageSprite;interface RasterDelegate;interface Storing;7.4 變量命名7.4.1采用大小寫混合的方式，第一個(gè)單詞的首字母小寫，其后單詞的首字母大寫；7.4.2變量名不應(yīng)以下劃線或美元符號(hào)開(kāi)頭；7.4.3盡量避免單個(gè)字符的變量名，除非是一次性的臨時(shí)變量。臨時(shí)變量通常被取名為i，j，k，m和n，它們一般用于整型；c，d，e，它們一般用于字符型；7.4.4不采用匈牙利命名法則，對(duì)不易清楚識(shí)別出該變量類型的變量應(yīng)使用類型名或類型名縮寫作其后綴，例如：Thread animationThread;String responseStr;7.4.5組件或部件變量使用其類型名或類型名縮寫作其后綴，例如：Command backCommand;Image barImage；TextField passwordField;Player dogSoundPlayer;7.4.6集合類型變量，例如數(shù)組和矢量，應(yīng)采用復(fù)數(shù)命名或使用表示該集合的名詞做后綴：Image images;Vector requestQueue;7.5 常量命名全部采用大寫，單詞間用下劃線隔開(kāi)：static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1;7.6 方法命名方法名是一個(gè)動(dòng)詞，采用大小寫混合的方式，第一個(gè)單詞的首字母小寫，其后單詞的首字母大寫；取值類可使用get前綴，設(shè)值類可使用set前綴，判斷類可使用is(has)前綴。getName();setSarry();isLogon();8 聲明8.1類或接口聲明類、接口定義語(yǔ)法規(guī)范：可見(jiàn)性(abstract|final) Class|Interface class_name(extends|implements)父類或接口名例如：public class GameScreen extends Canvas implements CommandListener, Runnable, HttpPosterListener8.2方法聲明8.2.1良好的程序設(shè)計(jì)應(yīng)該盡可能減小類與類之間耦合，所遵循的經(jīng)驗(yàn)法則是：盡量限制成員函數(shù)的可見(jiàn)性。如果成員函數(shù)沒(méi)必要公有 (public)，就定義為保護(hù) (protected)；沒(méi)必要保護(hù) (protected)，就定義為私有 (private)；8.2.2方法定義語(yǔ)法規(guī)范： 可見(jiàn)性abstract static final synchronized返回值類型 method_name(參數(shù)列表)(throws)異常列表 例如：private void sendLoginRequest(String username, String password) throws IOException 8.2.3聲明順序：構(gòu)造方法靜態(tài)公共方法靜態(tài)私有方法公共方法友元方法受保護(hù)方法私有方法main方法8.2.4方法參數(shù)建議順序：(被操作者，操作內(nèi)容，操作標(biāo)志，其他)：public void replace(String sourceStr, /源字串String oldStr, /被替換字串 String newStr) /替換為字串 （建議性）8.3變量聲明8.3.1一行一個(gè)聲明；8.3.2聲明局部變量的同時(shí)初始化（在變量的初始值依賴于某些先前發(fā)生的計(jì)算的特殊情況下可以不用同時(shí)初始化）； 8.3.3只在代碼塊的開(kāi)始處聲明變量，（一個(gè)塊是指任何被包含在大括號(hào)和中間的代碼）不要在首次用到該變量時(shí)才聲明；8.3.4避免聲明的局部變量覆蓋上一級(jí)聲明的變量，即不要在內(nèi)部代碼塊中聲明相同的變量名；8.3.5公共和保護(hù)的可見(jiàn)性應(yīng)當(dāng)盡量避免，所有的字段都建議置為私有，由獲取和設(shè)置成員函數(shù)（Getter、Setter）訪問(wèn)；8.3.6定義一個(gè)變量或者常量的時(shí)候，不要包含包名（類似java.security.MessageDigest digest = null），而要定義成下面的格式，除非是兩個(gè)包有相同的類名：import java.security.MessageDigest;MessageDigest digest = MessageDigest.getInstance(MD5);8.3.7字段定義語(yǔ)法規(guī)范：(public|private|protected) static final data_type field_name = expression ;例如：private static final int TILE_WIDTH = 16;8.3.8數(shù)組聲明時(shí)應(yīng)當(dāng)將跟在類型后，而不是字段名后：private Image images;private int slowerTicks;/不要用這種數(shù)組聲明方式8.3.9聲明順序：常量類變量實(shí)例變量：公有字段受保護(hù)字段友元字段私有字段/ 常量public final static double PI = 3.9793;/ 類變量protected static String key = “Love”;/ 實(shí)例變量/* * 共有字段 */public String userName = “Tom”;/* * 受保護(hù)字段 */protected float price = 0.0;/* * 友元字段 */Vector vPorducts = null;/* * 私有字段 */private int count;9 異常9.1捕捉異常的目的是為了處理它。9.2多個(gè)異常應(yīng)分別捕捉并處理，避免使用一個(gè)單一的catch來(lái)處理。10 習(xí)慣10.1 if、for、do、while等語(yǔ)句的執(zhí)行語(yǔ)句部分無(wú)論多少都要加括