XL-QP-30-07-JAVA编码规范.doc

JAVA编码规范版本：1.0作者： _日期： _2007.12.2_目录第一章布局结构规范41.1一般规则41.2源文件结构41.3类头部说明51.4方法头部说明61.5目录结构7第二章书写排版规范82.1一般规则82.2类的头（Class Headers）82.3方法的头（Method Headers）82.4缩进82.5空格92.6空行102.7括号和回车102.8对齐102.9长行拆分12第三章命名规范133.1一般规则133.2包的命名（Package Names）143.3类的命名（Class Names）143.4对象（类实例）的命名（Object Names）143.5字段的命名（Field Names）143.6类变量的命名（Class Variables Names）153.7本地变量的命名（Local Variables Names）153.8方法的命名（Methods Names）163.9常量的命名（Constants Names）163.10异常的命名（Exceptions Names）17第四章语言规范174.1变量174.2变量的初始化184.3方法184.4表达式194.5语句20IF语句20Switch语句21循环语句214.6final关键字224.7构造方法224.8注释234.9编码优化24前言本细则主要适用于在各种平台上用JAVA语言编写的源代码，旨在统一源代码的编码规范，增加其可读性、减少错误的发生，并最终形成良好的编码风格，特制订本规范。注：本文中标注【规则*-*-*】的条款必须严格执行，标注【建议*-*-*】的条款为提倡采用。适用范围本规范适用于采用JAVA语言进行开发的所有软件产品和应用系统（合作公司人员也应遵守），在各产品（应用系统）的开发过程中，如果出现与本规范相抵触（或需要对本规范进行扩展时），必须先编制出该产品（应用系统）的编程规范，并报请上级部门，经批准后方能执行。 第一章 布局结构规范1.1 一般规则【规则1-1-1】一个源程序文件（.Java文件）应该包括一个公共类（也可以包含额外的非公共类）。【规则1-1-2】每个源程序文件的头部必须包含类的头部说明和修改记录（与头部说明合并）。【建议1-1-3】每个方法头部必须包含方法头部说明。1.2 源文件结构【规则1-2-1】源文件各部分的书写顺序如下： 包的名字 Package name 引进部分 Import section 类的定义 Class definition ： q 类的头部说明Class header description q 类的定义Class definition q 常数Constants (final class variables): public, protected, privateq 类的变量Class variables (只有private)q 字段Fields (instance variables) (只有private)q 构造器（构造方法）Constructors（含说明）q 方法的定义 Method definition (public, protected, private) ：- 方法头部说明 Method header description - 方法的定义 Method definition- 方法体Method body q 公共的静态内部类Public static inner classesq 被保护的内部类Protected inner classes, static 或其他q 私有的内部类Private inner classes, static 或其他【规则1-2-2】相关的方法应该放置在一起。【规则1-2-3】当需要覆盖父类（superclass）的方法时，要保持这些方法和原父类的排列顺序一致，最好是放在一起。【规则1-2-4】在引进部分（import section）应清晰地列出每一个被引进的具体类。例如：正确的写法：import java.applet.AppletContext;错误的写法：import java.applet.*;1.3 类头部说明【规则1-3-1】类的头部说明必须包含类名、系统名称、软件版权、功能说明、作者、程序版本、各版本的修改日期和修改人员姓名、修改内容说明等几个部分，参考类为可选项。各部分次序如下：类名当前类的中文名称软件版权熙菱软件技术有限公司功能说明类功能的简要描述作者作者姓名程序版本程序版本号修改（开发）日期修改（开发）日期修改（开发）人员修改（开发）人员姓名修改（开发）内容说明修改（开发）内容的简要描述参考类（可选）相关参考类类名【规则1-3-2】类的头部说明应该使用如下格式（为了便于产生易懂、易用的javadoc文档，必要时请用换行）：/* * 类名: 类的中文名称 * 软件版权 * 功能说明：类功能的简要描述 * author 作者 * version 1.00 9999/99/99 作者姓名发布 * 9.99 9999/99/99 修改人员修改内容说明 * 9.99 9999/99/99 修改人员修改内容说明 * see 参考类1 * see 参考类2 */例如：/* * 类名: 工作流引擎主类 * 熙菱软件技术有限公司 * 功能说明：根据请求启动任务，调度任务；提供工作流相关应用层服务 * author 李世昕 * version 1.00 2002/05/10 李世昕发布 * 1.01 2002/05/20 吾买尔江增加补充资料功能 * 1.02 2002/06/15 吾买尔江 修改交易修改后不执行进入下一步的错误 * see SSBusiException * see WFATaskState */1.4 方法头部说明【规则1-4-1】方法头部说明必须包含方法名称、方法功能说明、输入参数列表、返回结果、抛出的异常列表等几个部分，参考类和调用说明为可选项。各部分次序参考如下：方法名称本方法的中文名称方法功能说明简述方法的功能输入参数列表必须全部列出，以提高准确性、易读性返回结果方法返回值的含义和取值范围抛出的异常列表方法中抛出的异常及其抛出条件参考类（可选）相关参考类类名调用说明（可选）调用方法的举例说明【规则1-4-2】方法头部说明应该使用如下格式（为了便于产生易懂、易用的javadoc文档，必要时请用换行）：/* * 方法名: 本方法的中文名称 * 功能说明：方法功能的简要描述 * param 参数数据类型参数名中文描述 * param 参数数据类型参数名中文描述 * return 返回结果数据类型及其相关说明 * throws 异常类型.错误代码 此类异常的抛出条件 * throws 异常类型.错误代码 此类异常的抛出条件 * see 参考类1 * see 参考类2 * 调用说明：调用方法的举例说明 */例如：/* * 方法名: 进入下一个工作步骤 * 功能说明：将当前任务从当前工作步骤带入下一工作步骤 * param intnTrxSn功能序号 * param String strCurrTaskId当前任务编号 * return String 下一步任务编号数组；若没有下一步，则返回null * throws 业务逻辑错误.2060 工作步骤表配置与条件选择结果不符 * throws 程序逻辑错误.2041 当前任务表无此任务记录 * see AppContext * see WFATaskState * 调用说明： * 先用构造方法： * WFTask objWFTask = new WFTask(ac) * 再调用本方法： * String straTaskList = objWFTask.gotoNextStep(nTrxSn,strCurrTaskId) */第二章 书写排版规范2.1 一般规则【规则2-1-1】不允许把多个短语句写在一行中，即一行最多只写一条语句。【规则2-1-2】合理使用空格、空行、对齐、缩行、长行拆分等方式格式化源代码，使程序舒展，可读。2.2 类的头（Class Headers）【规则2-2-1】尽量把类的头写在一行上。如果一行不够空间，则在出现extends和implements之前就换行，接下来的一行缩进。2.3 方法的头（Method Headers）【规则2-3-1】尽量将方法的头（method headers）写在一行上。如果一行不够空间，则依次在“throws”关键字前或“（”后立即换行，这样就把所有的参数放在了同一行上。如果还不够空间，一行就只放置一个参数。2.4 缩进【规则2-4-1】标准的缩进应该是4个空格。实际上一个缩进就是一个tab（tab应该被设置为显示4个空格）。建议缩进时只使用tab键。【规则2-4-2】仅在缩进时使用tab。在使用缩进后写的空格应该用实际的空格符，以便无论一个tab有多少空格，代码格式都是合理的。【规则2-4-3】在方法体的开始、结构/联合的定义、常量，公共和私有变量的定义以及循环、判断等语句中的代码都要采用缩进。例如：提倡的风格不提倡的风格void Method(int x)program codevoid Method(int x)program codePublic class WFTaskpublic int nPageNo = 2040;public string strTaskId;private char cTaskRank;Public class WFTaskpublic int nPageNo = 2040;public string strTaskId;private char cTaskRank;if (condition)program codeelseprogram codeif (condition)program codeelseprogram code【规则2-4-4】同层次的代码在同层次的缩进层上。2.5 空格【规则2-5-1】在以下情况时应使用一个空格： 在操作运算符之间 在定义和调用方法时，在参数列表的逗号后面 在For循环的分号后面 在逻辑运算符的前面和后面【规则2-5-2】在以下情况下不应使用空格： 在一个方法名和左括号“（”之间 在定义和调用方法时，“（”和“）”符号的左右 在定义一个数组或其参数时，“”和“”符号的左右2.6 空行【规则2-6-1】在相关的代码中，使用空行来分隔代码“段”。2.7 括号和回车【建议2-7-1】总是使用大括号“”，即使括号内只有一条语句。这样能避免常见的错误和简便维护。例如：正确的写法：if (nBottom nIndex) this.nTopRow = nIndex this.nRows; else if (nIndex this.nTopRow) this.nTopRow = nIndex; 不提倡的写法：if (nBottom nIndex) this.nTopRow = nIndex this.nRows; else if (nIndex= very_longer_variable12)& (very_longer_variable3 = very_longer_variable14)& (very_longer_variable5 = very_longer_variable16) dosomething();for (very_longer_initialization; very_longer_condition; very_longer_update)dosomething(); 第三章 命名规范3.1 一般规则【规则3-1-1】命名应当直观且可以拼读，可望文知意，便于记忆和阅读。标识符最好采用英文单词或其组合，避免使用拼音。程序中的英文单词一般不会太复杂，用词应当准确。例如不要把CurrentValue写成NowValue。【规则3-1-2】尽量避免名字中出现数字编号，如Value1,Value2等，除非逻辑上的确需要编号。这是为了防止程序员偷懒，不肯为命名动脑筋而导致产生无意义的名字（因为用数字编号最省事）。【规则3-1-3】本地变量不应该与类变量和字段名重名。【规则3-1-4】变量（字段，类变量，本地变量）建议用匈牙利命名法，即第一个小写字母（数据类型前缀）表示变量的数据类型，其后使用英文命名变量，单词(或缩写)第一个字母大写。例如：private int nTaskSn;public String strTaskId;【规则3-1-5】简单数据类型的前缀表：数据类型变量名前缀例子booleanbbCustomExist, baCustomExistcharccSymbol, caSymbolsbyteyyByte, yaBytesshortssHour, saHoursintnnLen, nLoopCounter, naLengthlongllMemory, laTimesfloatffLength, faLengthdoubleddMile, daMiles注：byte与int类型的前缀较特殊，使用时应注意【建议3-1-6】数组在数据类型前缀后加数组前缀a。例如：private int naTaskSn;public String straTaskId;3.2 包的命名（Package Names）【规则3-2-1】包名应该都用小写字母组成。3.3 类的命名（Class Names）【规则3-3-1】类名采用第一个字母大写其他字母小写的形式。【规则3-3-2】由多个单词组成的类名采用单词的第一个字母大写其他小写的形式。例如：Class FunctionPanel 3.4 常用对象（类实例）的命名【建议3-4-1】常用对象建议采用 对象名 + 对象类型名例如：personList 、personMap3.5 字段的命名（Field Names）【规则3-5-1】一个字段是一个非静态的成员变量，有时又被称为实变量（instance variable）。【规则3-5-2】字段名建议使用匈牙利前缀（Hungarian prefixes）。被引用时应该明确地使用 “this.fieldName”来表示。例如：Class Square private int nSideLength;public int getArea() return this.nSideLength* this.nSideLength;3.6 类变量的命名（Class Variables Names）【规则3-6-1】一个类变量是一个静态的成员变量。【规则3-6-2】所有的类变量名建议使用匈牙利前缀（Hungarian prefixes）。被引用时应该明确地使用“ClassName.classVarName”来表示。例如：Class Screen private static String strBranchNo;static Bitmap getBitmap()return Screen.strBranchNo;3.7 本地变量的命名（Local Variables Names）【规则3-7-1】本地变量是指在方法中定义的变量。【规则3-7-2】本地变量的命名建议使用匈牙利前缀（Hungarian prefixes）。它在程序代码中很容易被辨别，因为它没有前缀“this.”。例如：static int getPerimeter() int nPerimeter = 0;int naSsideList = this.getSideList();for (int i = 0; i = b & c d & c + f = g + h; 复合表达式过于复杂【规则4-4-3】不要有多用途的复合表达式。例如：d = (a = b + c) + r; 该表达式既求a值又求d值。应该拆分为两个独立的语句：a = b + c;d = a + r;【规则4-4-4】尽量避免含有否定运算的条件表达式。例如：/正确的写法：if (nNum = 10)【建议4-4-5】把boolean值和true 或 false值相比较时，采用隐式比较而不用显式比较。例如：/正确的写法： if (valid)if (!valid)/不提倡的写法：if (bValid = true)if (bValid = false)【规则4-4-6】字符串比较不能直接使用“=”运算符，而必须使用String类提供的 int compareTo(String anotherString)或int compareToIgnoreCase(String str)方法，也可使用boolean equals(ObjectanObject) 方法进行比较。例如：/正确的写法： if (strNpareTo(David)/错误的写法：if (strName = David)4.5 语句IF语句【规则4-5-1】if语句本身自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加。例如：/提倡的风格： if (nWidth nHeight)dosomething();/不提倡的风格：if (nWidth nHeight) dosomething();【规则4-5-2】通过使用额外的boolean变量来分解复杂的条件表达式，降低复杂性。例如：/复杂难懂的： if (nElement 0 | MAX_ELEMENTS nElement |nElement = nLastElement) /清晰的：final boolean bFinished = (nElement 0 |MAX_ELEMENTS nLastElement);final boolean bRepeatedEntry = (nElement = nLastElement);if (bFinished | bRepeatedEntry )【建议4-5-3】如果需要编写一连串的ifthen语句，建议先编写最常用的那部分。【建议4-5-4】字符串做相等比较时，将常数写在前面，变量写在后面。Switch语句【规则4-5-4】每个case语句的结尾绝对不要忘了加break，否则将导致多个分支重叠（除非有意使多个分支重叠）。【规则4-5-5】不要忘记最后那个default分支。即使程序真的不需要default处理，也应该保留语句：default : break;循环语句【建议4-5-6】尽量使用for循环。使用for循环的好处是它把整个循环的控制都放在一个地方来设置，而且它可以还让你定义一个控制变量，该变量不能从循环的外部访问。例如：for (int nIndex = 0; nIndex vCollection.size(); nIndex + )【建议4-5-7】在多重循环中，如果有可能，应当将最长的循环放在最内层，最短的循环放在最外层，以减少CPU跨切循环层的次数。例如：/长循环在最内层，效率高for (nCol=0; nCol5; nCol+ )for (nRow=0; nRow100; nRow+)nSum = nSum + anRownCol;/长循环在最外层，效率低for (nRow=0; nRow100; nRow+)for ( nCol=0; nCol5; nCol+ )nSum = nSum + anRownCol;【建议4-5-3】建议for语句的循环控制变量的取值采用“半开半闭区间”写法。半开半闭区间写法和闭区间写法虽然功能是相同，但相比之下，半开半闭区间写法写法更加直观。例如：/半开半闭区间写法for (nIndex = 0; nIndex 10; nIndex +)/闭区间写法for (nIndex = 0; nIndex = 9; nIndex +)4.6 final关键字【规则4-6-1】一个final类不能被继承。【规则4-6-2】一个final方法不能被覆盖。【规则4-6-3】一个final变量不能被改变。4.7 构造方法【建议4-7-1】一个类通常只有一个“主”构造方法。额外的简易（convenience）构造方法也有可能被定义，但他们应该按照主构造方法的形式来执行。这样做的意义是为了避免重复的代码。例如：/主构造方法public MultiLineLabel（String strLabel, int nMarginWidth）this.strPubLabel = strLabel;this.nPubMarginWidth = nMarginWidth;/错误的构造方法public MultiLineLabel（String strLabel）this.strPubLabel = strLabel;this.nPubMarginWidth = 0;/错误构造方法的改正public MultiLineLabel（String strLabel）this（strLabel,0）;4.8 注释【建议4-8-1】在代码中尽量使用“/”风格的注释，而不使用“/* . */”的注释（除非注释比较多或有规范要求的）。这样可以允许你使用“/* . */”来把大范围的代码转换为注释。【规则4-8-2】注释应当准确、易懂，防止有二义性。错误的注释不但无益反而有害。【规则4-8-3】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要及时删除。【规则4-8-4】注释是对代码逻辑的描述，而不是文档或代码的翻译。程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱。【规则4-8-5】一目了然的语句不加注释。例如：nIndex +;/nIndex加1多余的注释【规则4-8-6】对于全局数据（全局变量、常量定义等）必须要加注释。【规则4-8-7】在单独的注释行前加一空白行。如果此注释很重要，那么在它下面也加一行空白行