腾讯编码规范剖析

腾讯集团管理标准GL/YF013-2007V1.0-L1Java编码规范2007-09-11发布2007-09-11实施———————————————————————————————————腾讯集团发布GL/YF013-2007V1.0-L1前言本标准系公司首次发布实施，主要针对公司所有软件产品源代码范围的Java编码风格，对Java文件的文件组织、代码风格、注释、命名、声明、异常、习惯等方面均作出规范，以保障公司项目代码的易维护性和编码安全性。本标准由研发管理部、3G产品中心共同制定。本标准主要起草人：Junjun(张莉珺)、Iron（邱会发）本标准主要审核人：anwenfeng(冯文信)、Paulinesong(宋虹漫)、Ericlin（林松）、Stevezheng(郑全战)、Junehuang(黄俊)、Kevinxu(许冠严)、polo(陈广域)、leon（郭凯天）本标准批准人：jeffxiong(熊明华)、charles(陈一丹)、tony（张志东）、ponyma（马化腾）本标准首次发布日期：2007年9月11日本标准发送部门：公司各部门GL/YF013-2007V1.0-L12JAVA编码规范1目的为形成公司统一的Java编码风格，以保障公司项目代码的易维护性和编码安全性，特制定本规范。2适用范围本标准适用于腾讯集团（含分公司等各级分支机构）所有使用Java作为开发语言的软件产品。本标准中“腾讯集团”是指腾讯控股有限公司、其附属公司、及为会计而综合入账的公司，包括但不限于腾讯控股有限公司、深圳市腾讯计算机系统有限公司、腾讯科技（深圳）有限公司、腾讯科技（北京）有限公司、深圳市世纪凯旋科技有限公司、时代朝阳科技（深圳）有限公司、腾讯数码（深圳）有限公司、深圳市财付通科技有限公司。3总体原则所有使用Java作为开发语言的软件产品都须遵照本规范的内容进行编码。4文件组织4.1规则4.1.1由于超过2000行的程序难以阅读，应该尽量避免出现超过2000行的程序；4.1.2一个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。4.2组织顺序GL/YF013-2007V1.0-L134.2.1文件注释（参见6.1文件注释）；4.2.2包和引入语句：在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句；4.2.3类或接口注释（参见6.2类或接口注释）；4.2.4类或接口的声明；4.2.5类或接口的实现注释：如果有关类或接口的信息不适合作为“类或接口文档注释”，可以在类或接口的实现注释中给出；4.2.6类的（静态）变量：首先是类的公共变量，随后是保护变量，再后是包一级别的变量（没有访问修饰符），最后是私有变量；4.2.7实例变量：首先是公共级别的，随后是保护级别的，再后是包一级别的（没有访问修饰符），最后是私有级别的；4.2.8构造方法；4.2.9方法：方法应该按功能分组，而不应该按作用域或访问权限进行分组。4.3范例直接查看以下文件可以找到编码套用的规则：（注：可以通过复制粘贴保存到硬盘）5代码风格5.1缩进5.1.1程序块要采用缩进风格编写，缩进只使用TAB键，不能使用空格键（编辑器中请将TAB设置为4格）；5.1.2方法体的开始、类的定义、以及if、for、do、while、switch、case语句中的代码都要采用缩进方式；5.2对齐5.2.1程序块的分界符左大括号{和右大括号}都另起一行，应各独占一行并且位于同一列，同时与引用它们的语句左对齐；GL/YF013-2007V1.0-L145.2.2对齐只使用TAB键，不使用空格键；5.2.3不允许把多个短语句写在一行中，即一行只写一条语句；5.2.4if、for、do、while、case、switch、default等语句自占一行。5.3换行一行的长度超过80个字符需要换行，换行规则如下：5.3.1在一个逗号后面断开；5.3.2在一个操作符前面断开；5.3.3长表达式要在低优先级操作符处划分新行；5.3.4新行缩进2个TAB。5.4间隔5.4.1类、方法及相对独立的程序块之间、变量说明之后必须加空行；5.4.2关键字之后要留空格，象if、for、while等关键字之后应留一个空格再跟左括号（，以突出关键字；5.4.3方法名与其左括号（之间不要留空格,以与关键字区别；5.4.4二元操作符如=、+==、=、+、*、%、&&、||、,^等的前后应当加空格；5.4.5一元操作符如!、~、++、--等前后不加空格；5.4.6象［］、.这类操作符前后不加空格；5.4.7for语句中的表达式应该被空格分开，如：5.4.8强制转型后应该跟一个空格，如：6注释原则：——对已经不推荐使用的类和方法需要注明@Deprecated，并说明替代的类或者方法；myMethod((byte)aNum,(Object)x)for(expr1;expr2;expr3)GL/YF013-2007V1.0-L15——对于针对集合、开关的方法，要在方法注释中表明是否多线程安全。6.1文件注释所有的源文件都应该在开头有一个注释，其中列出文件的版权声明、文件名、功能描述以及创建、修改记录：6.2类或接口注释采用JavaDoc文档注释，在类、接口定义之前应当对其进行注释，包括类、接口的描述、最新修改者、版本号、参考链接等：注：JavaDoc文档注释：描述Java的类、接口、构造方法、方法、以及字段。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前。文档注释的第一行(/**)不需缩进，随后的文档注释每行都缩进1格(使星号纵向对齐)。/***描述*@author作者（最新修改者）*@version版本号（最新版本号）*@see参考的JavaDoc*/classWindowextendsBaseWindow{...}/**Copyright(C)1998-2006TENCENTInc.AllRightsReserved.**FileName：KQQMIDlet.java**Description：简要描述本文件的内容**History：*版本号作者日期简要介绍相关操作*1.0Iron2005-01-21Create*1.1Iron2005-01-30AddLogoScreen*/GL/YF013-2007V1.0-L166.3字段注释采用JavaDoc文档注释，定义为public的字段必需给出注释，在类的(静态)变量、实例变量定义之前当对其进行注释，给出该字段的描述等：6.4方法注释采用JavaDoc文档注释，在方法定义之前当对其进行注释，包括方法的描述、输入、输出及返回值说明、抛出异常说明、参考链接等：6.5其它注释(非JavaDoc文档注释)6.5.1单行代码注释一律使用注释界定符//，例如：/***描述*@param参数说明：每个参数一行，注明其取值范围等*@return返回值：注释出失败、错误、异常时的返回情况*@exception异常：注释出什么条件下会引发什么样的异常*@see参考的JavaDoc*/publiccharcharAt(intindex){...}/***描述*/intx=1263732;GL/YF013-2007V1.0-L176.5.2多行注释使用注释界定符/*...*/，例如：7命名7.1基本规则7.1.1使用可以准确说明变量、字段、类、接口、包等完整的英文描述符；7.1.2采用大小写混合，提高名字的可读性；7.1.3采用该领域的术语；尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等；7.1.4避免使用相似或者仅在大小写上有区别的名字。7.2包命名7.2.1包名一律小写,少用缩写和长名；7.2.2采用以下规则：[基本包].[项目名].[模块名].[子模块名]...7.2.3基本包：com.tencent或com.qq；7.2.4不得将类直接定义在基本包下，所有项目中的类、接口等都应当定义在各自的项目/**Hereisablockcommentwith*multiplelinesfortextcomments.*///explainwhatthismeansif(bar1){……}intisShow=0;//是否显示GL/YF013-2007V1.0-L18和模块包中；例如：7.3类或接口命名类或接口名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免用缩写词(除非该缩写词被更广泛使用，像URL，HTML)。例如：7.4变量命名7.4.1采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写；7.4.2变量名不应以下划线或美元符号开头；7.4.3尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型；7.4.4不采用匈牙利命名法则，对不易清楚识别出该变量类型的变量应使用类型名或类型名缩写作其后缀，例如：7.4.5组件或部件变量使用其类型名或类型名缩写作其后缀，例如：CommandbackCommand;ImagebarImage；TextFieldpasswordField;PlayerdogSoundPlayer;ThreadanimationThread;StringresponseStr;classRaster;classImageSprite;interfaceRasterDelegate;interfaceStoring;packagecom.tencent.kqq;packagecom.tencent.kqq.util;GL/YF013-2007V1.0-L197.4.6集合类型变量，例如数组和矢量，应采用复数命名或使用表示该集合的名词做后缀：7.5常量命名全部采用大写，单词间用下划线隔开：7.6方法命名方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写；取值类可使用get前缀，设值类可使用set前缀，判断类可使用is(has)前缀。8声明8.1类或接口声明类、接口定义语法规范：[可见性][('abstract'|'final')][Class|Interface]class_name[('extends'|'implements')][父类或接口名]{}例如：getName();setSarry();isLogon();staticfinalintMIN_WIDTH=4;staticfinalintMAX_WIDTH=999;staticfinalintGET_THE_CPU=1;Image[]images;VectorrequestQueue;GL/YF013-2007V1.0-L1108.2方法声明8.2.1良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有(public)，就定义为保护(protected)；没必要保护(protected)，就定义为私有(private)；8.2.2方法定义语法规范：[可见性]['abstract'][‘static’]['final']['synchronized'][返回值类型]method_name(参数列表)[('throws')][异常列表]{}例如：8.2.3声明顺序：构造方法静态公共方法静态私有方法公共方法友元方法受保护方法私有方法main方法8.2.4方法参数建议顺序：(被操作者，操作内容，操作标志，其他)：privatevoidsendLoginRequest(Stringusername,Stringpassword)throwsIOException{}publicclassGameScreenextendsCanvasimplementsCommandListen