1、4.2.1 注释类型 34.2.2 注释规则 44.3 Java结构规范 64.3.1 版权信息 64.3.2 包的定义 64.3.3 类的定义 74.4 Java格式规范 104.4.1 文档化 104.4.2 缩进 104.4.3 括号 104.4.4 页宽与换行 114.4.5 空白空间 134.4.6 枚举类型 144.4.7 数组初始化 144.4.8 Annotations 144.4.9 修饰符 154.5 表达式和语句规范 154.5.1 运算符的优先级 154.5.2 复合表达式 164.5.3 简单语句 174.5.4 复合语句 174.5.5 返回语句 174.5.6 i
2、f语句 174.5.7 for语句 194.5.8 while语句 204.5.9 do-while语句 204.5.10 switch语句 204.5.11 try-catch语句 214.5.12 空语句块 214.6 特殊字符 224.6.1 空格字符 224.6.2 特殊转义字符串 224.6.3 非ASCII字符 224.7 其它要求 235、 C/C+开发语言 255.1 C/C+命名规范 255.2 C/C+结构规范 275.2.1 版权和版本的声明 275.2.2 头文件的结构 285.2.3 C/C+格式规范 295.2.4 空行 295.2.4.2 代码行 305.2.4.
3、3 代码行内的空格 315.2.4.4 对齐 315.2.4.5 长行拆分 325.2.4.6 修饰符的位置 325.2.5 C/C+注释规范 325.3 表达式和语句规范 335.3.1 表达式和基本语句 335.3.1.1 运算符的优先级 335.3.1.2 if 语句 335.3.1.3 循环语句的效率 335.3.1.4 语句的循环控制变量 345.3.1.5 switch 语句 355.3.1.6 goto 语句 355.3.2 常量 355.3.3 函数 355.3.3.1 注释 355.3.3.2 参数 355.3.3.3 返回值 365.3.3.4 函数内部实现 365.3.3
4、.5 其它 375.3.4 重载和内联 375.3.4.1 重载 375.3.4.2 内联 375.3.5 内存管理 375.3.6 类的构造函数、析构函数、成员函数与赋值函数 385.3.7 类的继承和组合 385.4 其他要求 386、 C#开发语言 396.1 C#命名规范 396.2 C#结构规范 406.2.1 程序目录结构 406.2.2 类设计规范 406.2.2.1 类和命名空间 406.2.2.2 抽象类设计 406.2.2.3 静态类设计 416.2.2.4 接口设计 416.2.2.5 枚举设计 416.2.3 成员设计规范 416.2.3.1 成员重载 416.2.3.
5、2 属性设计 416.2.3.3 事件设计 416.2.3.4 运算符重载 426.2.4 配置文件格式 426.2.5 接口报文格式 426.2.6 WebService接口格式 426.2.7 错误处理规范 426.3 C格式规范 436.3.1 注释格式 436.3.2 书写规范 446.4 表达式和语句规范 466.4.1 if-else语句 466.4.2 for语句 466.4.3 while语句 476.4.4 try-catch 476.4.5 Switch语句 486.5 其他要求 496.5.1 静态对象操作规则 496.5.2 数据库操作规则 506.5.3 异常的产生和
6、处理 506.5.4 对象实例的申请与释放 51附 录 A 52参考文献 522 前 言本规范根据开放平台开发语言要求,并结合我行应用系统开发语言经验进行编制。本规范与A1版本相比主要变化如下:(1) 根据Google Java Style完善Java开发语言的规范。(2) 增加4.7章节“Java内存管理的开发要求”。本规范由中国工商银行软件开发中心提出,中国工商银行软件开发中心管理。本规范负责起草单位:杭州三部、广州一部、北京三部、架构办。本规范主要起草人:曹峰、张帆、杜志文、郭维、郑镇湖。本规范于2011年9月首次发布,2012年6月第一次修订,2014年5月第二次修订。3 引 言为规范
7、我行开放平台应用开发代码,制定此规范。4 开放平台开发语言技术手册41、 范围本文规范了Java、C/C+、C开发语言编码规则,主要包括命名规则、注释规则、文件结构规则和编程规则等内容。本规范适用于软件开发中心。本规范的使用对象为上述单位涉及使用Java、C/C+、C开发语言从事应用系统开发的人员。42、 规范性引用文件无43、 术语和定义44、 Java开发语言4.1 Java命名规范(1) 宜使用完整的英文描述符。(2) 宜使用适用于相关领域的术语。(3) 宜使用大小写混合使名字可读。(4) 英文词不宜缩写,如果有缩写,其缩写名称宜为常用缩写,不宜自定义缩写方式,同一单词宜使用相同的表示法
8、。如果该英文单词没有常用缩写,请使用全称。(5) 标识符宜按其在应用中的含义由一个或多个词组成。可以是英文词,但严禁使用中文拼音。标识应该简洁,避免使用长的名字,不宜超过32个字母。例子:String variableUsedToStoreSystemInformation /太复杂了String systemInformation /正确,简单明了String sysInfo /过于简单(6) 避免使用类似的名字,或仅仅是大小写不同的名字, 禁止使用Java的保留字。(7) 除静态常量外,命名避免使用下划线。(8) 包的名字应由小写单词组成。如:java.lang(9) 类 Class的名字
9、宜由大写字母开头。Customer, Account(10) 变量 变量的名字应用一个小写字母开头,后面的单词用大写字母开头。firstName, lastName(11) 接口 采用完整的英文描述符说明接口封装,所有单词的第一个字母大写,宜以大写的“I”开头,名字后面加上后缀able,ible或者er。IContactable, IPrompter(12) 组件/部件 使用完整的英文描述说明组件的用途,末端应接上组件类型。okButton, customerList, fileMenu等试对比下列代码:btnCancel.Text = &Cancel / 不建议cancelButton.Te
10、xt = / 推荐(13) 异常 通常采用字母 e 表示异常。(14) 实参/参数 宜使用与需要赋值的字段同样的名字:setCounter(int size) this.size = size;(15) 获取成员函数 宜在被访问字段名的前面加上前缀get。getFirstName(), getLastName()(16) 布尔型的获取成员函数 宜用单词is做前缀。isPersistent(), isString()(17) 设置成员函数 宜在被访问字段名的前面加上前缀set。setFirstName(), setLastName(), setWarpSpeed()public void set
11、FirstName(String firstName) this.firstName = firstName;(18) 普通成员函数采用完整的英文描述说明成员函数功能,第一个单词宜采用动词,第一个字母小写。openFile(), addAccount()(19) 静态常量字段全部采用大写字母,单词之间用下划线分隔。MIN_BALANCE, DEFAULT_DATE(20) 循环计数器 宜采用字母 i,j,k 或者 counter。(21) 数组 数组宜用下面的方式来命名,规则与变量一致。是:byte buffer;而不是:byte buffer;(22) 文件名源码文件名由它所包含的顶级cla
12、ss的类名(大小写敏感),加上.java后缀组成。(除了package-info.java文件)。(23) 类型名类型名有两种命名方式:a、单独一个大写字母,有时后面再跟一个数字。(例如,E、T、X、T2)。b、像一般的class命名一样,再在最后接一个大写字母。(例如,RequestT、FooBarT)。4.2 Java注释规范44.2.1 注释类型(1) 文档注释 描述Java的类、接口、构造器,方法,以及字段。每个文档注释都会被置于注释定界符/*.*/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前: /* * The Example class provides . */ p
13、ublic class Example .注意顶层的类和接口不缩进,而其成员是缩进的。描述类和接口的文档注释的第一行(/*)不需缩进;随后的文档注释每行都缩进1格,应使星号纵向对齐。成员,包括构造函数在内,其文档注释的第一行缩进2个空格,随后每行都缩进3个空格。有关类、接口、变量或方法等不适合写在文档中的信息,可使用块注释或单行注释。例如,有关一个类实现的细节,应放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。文档注释不应放在一个方法或构造器的定义块中,因为Java会将位于文档注释之后的第一个声明与其相关联。对文档核心部分或进行大量修改时,宜在修改处注释作者和时间信息。(2) 多行注
14、释符一些不再使用但仍可保留参考,或在调试过程中想让它暂时失效的代码,可采用多行注释/*.*/说明。/* 这部分代码因为已被它之前的代码取代,由 B.Gustafsson, 于1999年6月4日注释掉。如果两年之后还未使用,将其删除.(源代码)*/(3) 单行注释在成员函数内采用单行注释,来说明业务逻辑、代码段和暂时变量的声明。注释符/后宜紧跟一个空格,然后是注释信息。/ 遵照 Sarek 的规定,给所有超过 $1000 的发货单/ 打 5% 的折扣。让利活动于 1995年 2 月开始.44.2.2 注释规则(1) 类 注释宜注释类的目的,类所完成的功能。(2) 接口注释 宜注释设置接口的目的,
15、及接口如何被使用以及如何不被使用。(3) 成员函数注释(a) 若成员变量已有说明,设置与获取成员函数可不加注释。(b) 对于普通成员函数,要求说明完成的功能,宜注释参数含义及返回值。(c) 对于普通成员函数内部控制结构,宜注释代码的功能及处理顺序等。(4) 实参/参数 注释宜注释参数含义、及其它任何约束或前提条件。(5) 字段/属性注释 宜注释字段描述。(6) 局部变量 注释局部变量如无特殊含义,可不加注释。(7) 段落空白行:是指javadoc中,上下两个段落之间只有上下对齐的 * 字符的行。每个段落的第一行在第一个字符之前,有一个标签,并且之后不要有任何空格。(8) 从句 所有标准的从句,
16、应该按照如下的顺序添加:param、return、throws、deprecated。并且这四种从句,不应该出现在一个没有描述的Javadoc块中。当从句无法在一行写完时,应该断行。延续行在第一行的字符的位置,缩进至少4个字符单位。(9) 摘要片段 每个类或者成员的javadoc,都是由一个摘要片段开始的。这个片段非常重要。因为它是类或者方法在使用时唯一能看到的文本说明。主要摘要只是一个片段,应该是一个名词短语或者动词短语,而不应该是一个完整的句子。但是它应该像一个完整的句子一样使用标点符号。 注意:一种常见的错误是以这种形式使用javadoc:/* return the customer I
17、D */.这是不对的。应该改为:/* Returns the customer ID. */.(10) 何处应该使用Javadoc 至少,Javadoc应该应用于所有的public类、public和protected的成员变量和方法。例外情况如下。例外1:方法本身已经足够说明的情况 当方法本身很显而易见时,可以不需要javadoc。例如:getFoo。没有必要加上javadoc说明“Returns the foo”。单元测试中的方法基本都能通过方法名,显而易见地知道方法的作用。因此不需要增加javadoc。有时候不应该引用此例外,来省略一些用户需要知道的信息。getCannicalName 。
18、当大部分代码阅读者不知道canonical name是什么意思时,不应该省略Javadoc,认为只能写/* Returns the canonical name. */ 。例外2:重载方法 重载方法有时不需要再写Javadoc。例外3:可选的javadoc 一些在包外不可见的class和成员变量或方法,根据需要,也可以使用javadoc。当一个注释用以说明这个类、变量或者方法的总体目标或行为时,可以使用Javadoc。4.3 Java结构规范源码文件按照先后顺序,由以下几部分组成:(1) License或者copyright声明信息。(如果需要声明)(2) 包声明语句。(3) import语句
19、。(4) class类声明(每个源码文件只能有唯一一个顶级class)。每个部分之间应该只有一行空行作为间隔。44.3.2 版权信息版权信息宜在 Java 文件的开头。/* * Copyright (c) 2011 ICBC. * All right reserved.不需要出现在 JavaDoc 的信息可包含在版权信息中。44.3.3 包的定义package 行应在 import 行之前,import 中标准的包名应在本地的包名之前,且按照字母顺序排列。对于Java代码中import其他的类,宜import为具体的类名,而不是import java.io.*。import语句应该被分为几个组
20、,每个组之间由单行的空行隔开。分组的顺序如下:(1) 所有的static import为归为一组。(2) com.icbc.ctp包的import归为一组。(3) 使用的第三方包的引用。每个顶级第三方包归为一组。第三方包之间按ASCII码排序。android, com, junit, org, sun(4) java包归为一组。(5) javax包归为一组。同一组内的import语句之间不应用空行隔开。package .stats;import java.io InputStream;import java.io OutputStream;import java.util.Observable
21、;import hotlava.util.Application;44.3.4 类的定义(1) 类的定义Java的类定义不支持多继承,声明继承应使用extends关键字。类可以实现多个接口,实现接口应用implements 关键字声明。public class CounterSet extends Observable implements Cloneable(2) 类的成员定义区类的成员变量定义顺序,宜是公共级别、保护级别、包一级别(没有访问修饰符),私有级别。 * Packet countersprotected int packets;public 的成员变量宜生成文档(JavaDoc)
22、。若protected、private和 package 定义的成员变量名字含义明确,可不加注释。(3) 每行声明变量的数量宜一行一个声明,利于注释。int level; / indentation levelint size; / size of tableObject currentEntry; / currently selected table entry优于:int level, size;不宜将不同类型变量的声明放在同一行。int foo, fooarray; / 不建议(4) 初始化应在声明局部变量时做初始化,除非变量的初始值依赖于某些先前发生的计算。(5) 布局一个代码块是指被
23、包含在大括号中间的代码。宜在代码块的开始处声明变量,不宜在首次用到该变量时才声明,for循环的索引变量除外。void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 例外for (int i = 0; i maxLoops; i+);避免声明的局部变量覆盖上一级声明的变量。不应在内部代码块中声明相同的变量名。如 int count; myMethod() int count = 0; / 应避免(6) 类的构造函数和重载方法类如
24、果存在多个构造函数或者多个同名成员方法,宜按参数的数量,参数多的构造函数或者成员方法放在后面,这些函数应该写在一起,不应该被其他成员分开。public CounterSet(int size) public CounterSet(int size,int value) this.value = value;(7) 类的公开方法类的公开方法宜写注释。 * Set the packet counters * (such as when restoring from a database)Public final void setArray(int r1, int r2, int r3, int r
25、4) throws IllegalArgumentException / / Ensure the arrays are of equal size if (r1.length != r2.length | r1.length != r3.length | r1.length != r4.length) throw new IllegalArgumentException(Arrays must be of the same size); System.arraycopy(r1, 0, r3, 0, r1.length); System.arraycopy(r2, 0, r4, 0, r1.l
26、ength);(8) 类的toString方法类宜定义自己的toString 方法。public String toString() StringBuffer retval = new StringBuffer( CounterSet: for (int i = 0; data.length(); i+) retval.append( data.bytes.toString().append(data.packets.toString(); return retva.toString();(9) 类的main方法类定义中的main() 方法宜写在类的底部。(10) 只声明唯一一个顶级class
27、每个源码文件中应只能有一个顶级class,package-info.java文件除外。(11) 类成员顺序类成员的顺序对代码的易读性有很大影响,但是没有一个统一正确的标准。不同的类可能有不同的排序方式。重要的是,每个class都要按照一定的逻辑规律排序。当被问及时,能够解释清楚为什么这样排序。例如,新增加的成员方法,不是简单地放在class代码最后面,按日期排序不是按逻辑排序。4.4 Java格式规范44.4.1 文档化应用 javadoc 为类生成文档,不宜使用 author 标记。44.4.2 括号左括号和后一个字符之间不宜出现空格,右括号和前一个字符之间也不宜出现空格。CallProc( aParameter );CallProc(aParameter); / 推荐括号应为达到某种目的而出现在源代码中,不宜在语句中使用无意义的括号。If(i) = 42) / 不建议。括号毫无意义if(i = 42) | (j = 42) then / 推荐 - 的确需要括号44.4.3 页宽与换行页宽宜设置为80个字符或者100个字符。一行的长度不应超过80个字符或者100个字符,超长的语句应该在一个逗号后或者一个操作符前折行。一条语句折行后,宜比原来的语句再缩进2个空格。除了以下几个特殊情况外,其他代码内容都需要遵守这个长度限制: 按照行长度限制,无法实
copyright@ 2008-2023 冰点文库 网站版权所有
经营许可证编号:鄂ICP备19020893号-2