1、华为Java语言编码规范样本Document number 文档编号 Confidentiality level 密级 内部公开Document version 文档版本 Total 29 pages 共 29 页V1.00Java语言编码规范Prepared by 拟制Date日期yyyy-mm-ddReviewed by 评审人Date日期yyyy-mm-ddApproved by批准Date日期yyyy-mm-ddRevision Record 修订记录Date日期Revision Version修订版本Sec No. 修改章节Change Description修改描述Author作者
2、yyyy-mm-ddVx.xxTable of Contents 目录 1.范畴本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST规则和建议。本规范合用于使用Java语言编程产品和项目。2.规范性引用文献下列文献中条款通过本规范引用而成为本规范条款。凡是注日期引用文献，其随后所有修改单（不涉及勘误内容）或修订版均不合用于本规范，然而，勉励依照本规范达到合同各方研究与否可使用这些文献最新版本。凡是不注日期引用文献，其最新版本合用于本规范。序号编号名称1公司- DKBA1040-.12Java语言编程规范3.术语和定义规则：编程时强制必要遵守原则。建议：编程时必要加以考虑原则。格
3、式：对此规范格式阐明。阐明：对此规范或建议进行必要解释。示例：对此规范或建议从正、反两个方面给出例子。4.排版规范4.1.规则4.1.1.*程序块要采用缩进风格编写，缩进空格数为4个。阐明：对于由开发工具自动生成代码可以有不一致。4.1.2.*分界符（如大括号和）应各独占一行并且位于同一列，同步与引用它们语句左对齐。在函数体开始、类和接口定义、以及if、for、do、while、switch、case语句中程序都要采用如上缩进方式。示例：如下例子不符合规范。for (.) . / program codeif (.) . / program code void example_fun( voi
4、d ) . / program code 应如下书写：for (.) . / program codeif (.) . / program code void example_fun( void ) . / program code 4.1.3.*较长语句、表达式或参数（80字符）要提成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出新行要进行恰当缩进，使排版整洁，语句可读。 示例：if (filename != null & new File(logPath + filename).length() LogConfig.getFileSize() . / progr
5、am code public static LogIterator read(String logType，Date startTime，Date endTime, int logLevel，String userName，int bufferNum) 4.1.4.*不容许把各种短语句写在一行中，即一行只写一条语句示例：如下例子不符合规范。LogFilename now = null； LogFilename that = null;应如下书写：LogFilename now = null;LogFilename that = null; 4.1.5.*if，for，do，while，case
6、，switch，default 等语句自占一行，且if，for，do，while等语句执行语句无论多少都要加括号。示例：如下例子不符合规范。if(writeToFile) writeFileThread.interrupt(); 应如下书写：if(writeToFile)writeFileThread.interrupt(); 4.1.6.*相对独立程序块之间、变量阐明之后必要加空行。示例：如下例子不符合规范。if(log.getLevel() LogConfig.getRecordLevel() return;LogWriter writer; 应如下书写：if(log.getLevel()
7、 LogConfig.getRecordLevel()return;LogWriter writer;int index; 4.1.7.*对齐只使用空格键，不使用TAB键。阐明：以免用不同编辑器阅读程序时，因TAB键所设立空格数目不同而导致程序布局不整洁。JBuilder、UltraEdit等编辑环境，支持行首TAB替代成空格，应将该选项打开。4.1.8.*在两个以上核心字、变量、常量进行对等操作时，它们之间操作符之前、之后或者先后要加空格；进行非对等操作时，如果是关系密切及时操作符（如.），后不应加空格。阐明：采用这种松散方式编写代码目是使代码更加清晰。由于留空格所产生清晰性是相对，因此，在
8、已经非常清晰语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号背面和右括号前面)不需要加空格，多重括号间不必加空格，由于在Java语言中括号已经是最清晰标志了。在长语句中，如果需要加空格非常多，那么应当保持整体清晰，而在局部不加空格。给操作符留空格时不要持续留两个以上空格。示例：（1）逗号、分号只在背面加空格。int a，b，c；（2）比较操作符，赋值操作符=、+=，算术操作符+、%，逻辑操作符&、&，位域操作符= MAX_TIME_VALUE) a = b + c;a *= 2;a = b 2; （3）!、+、-、&（地址运算符）等单目操作符先后不加空格。flag = !isEm
9、pty；/ 非操作!与内容之间i+； / +,-与内容之间 （4）.先后不加空格。p.id = pid； / .先后不加空格 （5）if、for、while、switch等与背面括号间应加空格，使if等核心字更为突出、明显。if (a = b & c d)4.2.建议类属性和类办法不要交叉放置，不同存取范畴属性或者办法也尽量不要交叉放置。格式：类定义类公有属性定义类保护属性定义类私有属性定义类公有办法定义类保护办法定义类私有办法定义5.注释规范5.1.规则5.1.1.普通状况下，源程序有效注释量必要在30以上。阐明：注释原则是有助于对程序阅读理解，在该加地方都加了，注释不适当太多也不能太少，注
10、释语言必要精确、易懂、简洁。可以用注释记录工具来记录。5.1.2.包注释：包注释写入一名为 package.html HTML格式阐明文献放入当前程径。阐明：以便JavaDoc收集示例：com/huawei/msg/relay/comm/package.html5.1.3.包注释内容：简述本包作用、详细描述本包内容、产品模块名称和版本、公司版权。阐明：在详细描述中应当阐明这个包作用以及在整个项目中位置。格式：一句话简述。详细描述。产品模块名称和版本公司版权信息 示例：为 Relay 提供通信类，上层业务使用本包通信类与SP进行通信。详细描述。MMSC V100R002 Relay(C) 版权所
11、有 - 文思创新技术有限公司 5.1.4.文献注释：文献注释写入文献头部，包名之前位置。阐明：注意以 /* 开始避免被 JavaDoc 收集示例：/* * 注释内容 */package m; 5.1.5.文献注释内容：版权阐明、描述信息、生成日期、修改历史。阐明：文献名可选。格式：/* * 文献名：文献名 * 版权：版权 * 描述：描述 * 修改人：修改人 * 修改时间：YYYY-MM-DD * 修改单号：修改单号 * 修改内容：修改内容 */ 阐明：每次修改后在文献头部写明修改信息，CheckIn时候可以直接把蓝色字体信息粘贴到VSS注释上。在代码受控之前可以免除。示例：/* * 文献名：L
12、ogManager.java * 版权：Copyright - Huawei Tech. Co. Ltd. All Rights Reserved. * 描述： MMSC V100R002 Relay 通用日记系统 * 修改人： 张三 * 修改时间：-02-16 * 修改内容：新增 * 修改人： 李四 * 修改时间：-02-26 * 修改单号：WSS368 * 修改内容：。 * 修改人： 王五 * 修改时间：-03-25 * 修改单号：WSS498 * 修改内容：。 */ 5.1.6.类和接口注释：该注释放在 package 核心字之后，class 或者 interface 核心字之前。阐明：
13、以便JavaDoc收集。示例：package m;/* * 注释内容 */public class CommManager 5.1.7.类和接口注释内容：类注释重要是一句话功能简述、功能详细描述。阐明：可依照需要列出：版本号、生成日期、作者、内容、功能、与其他类关系等。 如果一种类存在Bug，请如实阐明这些Bug。格式：/* * 一句话功能简述 * 功能详细描述 * author 作者 * version 版本号，YYYY-MM-DD * see 有关类/办法 * since 产品/模块版本 * deprecated */阐明：描述某些阐明该类或者接口功能、作用、用法和注意事项，每次修改后增长
14、作者和更新版本号和日期，since 表达从那个版本开始就有这个类或者接口，deprecated 表达不建议使用该类或者接口。示例：/* * LogManager 类集中控制对日记读写操作。 * 所有为静态变量和静态办法，对外提供统一接口。分派相应日记类型读写器， * 读取或写入符合条件日记纪录。 * author 张三，李四，王五 * version 1.2，-03-25 * see LogIteraotor * see BasicLog * since CommonLog1.0 */ 5.1.8.类属性、公有和保护办法注释：写在类属性、公有和保护办法上面。示例：/* * 注释内容 */pri
15、vate String logType;/* * 注释内容 */public void write() 5.1.9.成员变量注释内容：成员变量意义、目、功能，也许被用到地方。 5.1.10.公有和保护办法注释内容：列出办法一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。格式：/* * 一句话功能简述 * 功能详细描述 * param 参数1 参数1阐明 * param 参数2 参数2阐明 * return 返回类型阐明 * exception/throws 违例类型 违例阐明 * see 类、类#办法、类#成员 * deprecated */阐明：since 表达从那个版本开
16、始就有这个办法；exception或throws 列出也许仍出异常；deprecated 表达不建议使用该办法。示例：/* * 依照日记类型和时间读取日记。 * 分派相应日记类型LogReader， 指定类型、查询时间段、条件和重复器缓冲数， * 读取日记记录。查询条件为null或0表达无限制，重复器缓冲数为0读不到日记。 * 查询时间为左包括原则，即 startTime，endTime) 。 * param logTypeName 日记类型名（在配备文献中定义） * param startTime 查询日记开始时间 * param endTime 查询日记结束时间 * param logLe
17、vel 查询日记级别 * param userName 查询该顾客日记 * param bufferNum 日记重复器缓冲记录数 * return 成果集，日记重复器 * since CommonLog1.0 */public static LogIterator read(String logType，Date startTime，Date endTime， int logLevel，String userName，int bufferNum) 5.1.11.对于办法内部用throw语句抛出异常，必要在办法注释中标明，对于所调用其她办法所抛出异常，选取重要在注释中阐明。 对于非Runtime
18、Exception，即throws子句声明会抛出异常，必要在办法注释中标明。阐明：异常注释用exception或throws表达，在JavaDoc中两者等价，但推荐用exception标注Runtime异常，throws标注非Runtime异常。异常注释必要阐明该异常含义及什么条件下抛出该异常。 5.1.12.*注释应与其描述代码相近，对代码注释应放在其上方或右方（对单条语句注释）相邻位置，不可放在下面，如放于上方则需与其上面代码用空行隔开。5.1.13.*注释与所描述内容进行同样缩排。阐明：可使程序排版整洁，并以便注释阅读与理解。示例：如下例子，排版不整洁，阅读稍感不以便。public vo
19、id example( )/ 注释 CodeBlock One / 注释 CodeBlock Two应改为如下布局。public void example( ) / 注释 CodeBlock One / 注释 CodeBlock Two 5.1.14.*将注释与其上面代码用空行隔开。示例：如下例子，显得代码过于紧凑。/注释program code one/注释program code two 应如下书写：/注释program code one /注释program code two 5.1.15.*对变量定义和分支语句（条件分支、循环语句等）必要编写注释。阐明：这些语句往往是程序实现某一特定功
20、能核心，对于维护人员来说，良好注释协助更好理解程序，有时甚至优于看设计文档。 5.1.16.*对于switch语句下case语句，如果由于特殊状况需要解决完一种case后进入下一种case解决，必要在该case语句解决完、下一种case语句前加上明确注释。阐明：这样比较清晰程序编写者意图，有效防止无端漏掉break语句。 5.1.17.*边写代码边注释，修改代码同步修改相应注释，以保证注释与代码一致性。不再有用注释要删除。 5.1.18.*注释内容要清晰、明了，含义精确，防止注释二义性。阐明：错误注释不但无益反而有害。 5.1.19.*避免在注释中使用缩写，特别是不惯用缩写。阐明：在使用缩写时
21、或之前，应对缩写进行必要阐明。 5.2.建议5.2.1.*避免在一行代码或表达式中间插入注释。阐明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。 5.2.2.*通过对函数或过程、变量、构造等对的命名以及合理地组织代码构造，使代码成为自注释。阐明：清晰精确函数、变量等命名，可增长代码可读性，并减少不必要注释。 5.2.3.*在代码功能、意图层次上进行注释，提供有用、额外信息。阐明：注释目是解释代码目、功能和采用办法，提供代码以外信息，协助读者理解代码，防止没必要重复注释信息。示例：如下注释意义不大。/ 如果 receiveFlag 为真if (receiveFlag) 而
22、如下注释则给出了额外有用信息。 / 如果从连结收到消息 if (receiveFlag) 5.2.4.*在程序块结束行右方加注释标记，以表白某程序块结束。阐明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。示例：参见如下例子。if (.) program code1 while (index MAX_INDEX) program code2 / end of while (index MAX_INDEX) / 指明该条while语句结束 / end of if (.) / 指明是哪条if语句结束 5.2.5.*注释应考虑程序易读及外观排版因素，使用语言若是中、英兼有，建议
23、多使用中文，除非能用非常流利精确英文表达。阐明：注释语言不统一，影响程序易读性和外观排版，出于维护考虑，建议使用中文。 5.2.6.办法内单行注释使用 /。阐明：调试程序时候可以以便使用 /* 。*/ 注释掉一长段程序。5.2.7.注释尽量使用中文注释和中文标点。办法和类描述第一句话尽量使用简洁明了话概括一下功能，然后加以句号。接下来某些可以详细描述。阐明：JavaDoc工具收集简介时候使用选用第一句话。 5.2.8.顺序实现流程阐明使用1、2、3、4在每个实现环节某些代码前面进行注释。示例：如下是对设立属性流程注释 /1、判断输入参数与否有效。 。 / 2、设立本地变量。 。 5.2.9.某
24、些复杂代码需要阐明。示例：这里重要是对闰年算法阐明。 /1. 如果能被4整除，是闰年； /2. 如果能被100整除，不是闰年.； /3. 如果能被400整除，是闰年.。6.命名规范6.1.规则6.1.1.包名采用域后缀倒置加上自定义包名，采用小写字母。在部门内部应当规划好包名范畴，防止产生冲突。部门内部产品使用部门名称加上模块名称。产品线产品使用产品名称加上模块名称。格式：com.huawei.产品名.模块名称com.huawei.部门名称. 项目名称示例：Relay模块包名 com.huawei.msg.relay通用日记模块包名 com.huawei.msg.log 6.1.2.类名和接口
25、使用类意义完整英文描述，每个英文单词首字母使用大写、别的字母使用小写大小写混合法。示例：OrderInformation，CustomerList，LogManager，LogConfig 6.1.3.办法名使用类意义完整英文描述：第一种单词字母使用小写、剩余单词首字母大写别的字母小写大小写混合法。示例：private void calculateRate();public void addNewOrder(); 6.1.4.办法中，存取属性办法采用setter 和 getter办法，动作办法采用动词和动宾构造。格式：get + 非布尔属性名()is + 布尔属性名()set + 属性名()动
26、词()动词 + 宾语()示例：public String getType();public boolean isFinished();public void setVisible(boolean);public void show();public void addKeyListener(Listener); 6.1.5.属性名使用意义完整英文描述：第一种单词字母使用小写、剩余单词首字母大写别的字母小写大小写混合法。属性名不能与办法名相似。示例： private customerName;private orderNumber;private smpSession; 6.1.6.常量名使用全大
27、写英文描述，英文单词之间用下划线分隔开，并且使用 final static 修饰。示例： public final static int MAX_VALUE = 1000;public final static String DEFAULT_START_DATE = -12-08; 6.1.7.属性名可以和公有办法参数相似，不能和局部变量相似，引用非静态成员变量时使用 this 引用，引用静态成员变量时使用类名引用。示例：public class Person private String name; private static List properties; public void se
28、tName (String name) this.name = name; public void setProperties (List properties) Person.properties = properties; 6.2.建议6.2.1.惯用组件类命名以组件名加上组件类型名结尾。示例：Application 类型，命名以App 结尾MainAppFrame 类型，命名以Frame 结尾TopoFramePanel 类型，建议命名以Panel 结尾CreateCircuitPanelBean 类型，建议命名以Bean 结尾DataAccessBeanEJB 类型，建议命名以EJB 结尾DBProxyEJBApple
