开放平台开发语言技术手册.docx
《开放平台开发语言技术手册.docx》由会员分享，可在线阅读，更多相关《开放平台开发语言技术手册.docx（70页珍藏版）》请在冰豆网上搜索。
开放平台开发语言技术手册
开放平台开发语言技术手册
1.文件属性
文件属性
内容
文件名称
开放平台开发语言技术手册
文件编号
文件版本号
A2
文件状态
正式稿
作者
曹峰、张帆、杜志文、郭维、郑镇湖
文件初次发布日期
2007-1-9
文件初次实施日期
2007-1-9
2.文件变更历史清单
文件版本号
修正日期
修正人
备注
A1
2012-6-29
郭维
A2
2014-3-31
郑镇湖
3.本次修改变更说明
序号
变更内容简述
1.
A1：
增加第6章节C＃开发语言的要求
2.
A2：
根据GoogleJavaStyle完善Java开发语言的规范
3.
4.
5.
6.
1目录
目录II
前言V
引言VI
开放平台开发语言技术手册1
1、范围1
2、规范性引用文件1
3、术语和定义1
4、Java开发语言1
4.1Java命名规范1
4.2Java注释规范3
4.2.1注释类型3
4.2.2注释规则4
4.3Java结构规范6
4.3.1版权信息6
4.3.2包的定义6
4.3.3类的定义7
4.4Java格式规范10
4.4.1文档化10
4.4.2缩进10
4.4.3括号10
4.4.4页宽与换行11
4.4.5空白空间13
4.4.6枚举类型14
4.4.7数组初始化14
4.4.8Annotations14
4.4.9修饰符15
4.5表达式和语句规范15
4.5.1运算符的优先级15
4.5.2复合表达式16
4.5.3简单语句17
4.5.4复合语句17
4.5.5返回语句17
4.5.6if语句17
4.5.7for语句19
4.5.8while语句20
4.5.9do-while语句20
4.5.10switch语句20
4.5.11try-catch语句21
4.5.12空语句块21
4.6特殊字符22
4.6.1空格字符22
4.6.2特殊转义字符串22
4.6.3非ASCII字符22
4.7其它要求23
5、C/C++开发语言25
5.1C/C++命名规范25
5.2C/C++结构规范27
5.2.1版权和版本的声明27
5.2.2头文件的结构28
5.2.3C/C++格式规范29
5.2.4空行29
5.2.4.2代码行30
5.2.4.3代码行内的空格31
5.2.4.4对齐31
5.2.4.5长行拆分32
5.2.4.6修饰符的位置32
5.2.5C/C++注释规范32
5.3表达式和语句规范33
5.3.1表达式和基本语句33
5.3.1.1运算符的优先级33
5.3.1.2if语句33
5.3.1.3循环语句的效率33
5.3.1.4语句的循环控制变量34
5.3.1.5switch语句35
5.3.1.6goto语句35
5.3.2常量35
5.3.3函数35
5.3.3.1注释35
5.3.3.2参数35
5.3.3.3返回值36
5.3.3.4函数内部实现36
5.3.3.5其它37
5.3.4重载和内联37
5.3.4.1重载37
5.3.4.2内联37
5.3.5内存管理37
5.3.6类的构造函数、析构函数、成员函数与赋值函数38
5.3.7类的继承和组合38
5.4其他要求38
6、C#开发语言39
6.1C#命名规范39
6.2C#结构规范40
6.2.1程序目录结构40
6.2.2类设计规范40
6.2.2.1类和命名空间40
6.2.2.2抽象类设计40
6.2.2.3静态类设计41
6.2.2.4接口设计41
6.2.2.5枚举设计41
6.2.3成员设计规范41
6.2.3.1成员重载41
6.2.3.2属性设计41
6.2.3.3事件设计41
6.2.3.4运算符重载42
6.2.4配置文件格式42
6.2.5接口报文格式42
6.2.6WebService接口格式42
6.2.7错误处理规范42
6.3C＃格式规范43
6.3.1注释格式43
6.3.2书写规范44
6.4表达式和语句规范46
6.4.1if-else语句46
6.4.2for语句46
6.4.3while语句47
6.4.4try-catch47
6.4.5Switch语句48
6.5其他要求49
6.5.1静态对象操作规则49
6.5.2数据库操作规则50
6.5.3异常的产生和处理50
6.5.4对象实例的申请与释放51
附录A52
参考文献52
2
前言
本规范根据开放平台开发语言要求，并结合我行应用系统开发语言经验进行编制。
本规范与A1版本相比主要变化如下：
（1）根据GoogleJavaStyle完善Java开发语言的规范。
（2）增加4.7章节“Java内存管理的开发要求”。
本规范由中国工商银行软件开发中心提出，中国工商银行软件开发中心管理。
本规范负责起草单位：
杭州三部、广州一部、北京三部、架构办。
本规范主要起草人：
曹峰、张帆、杜志文、郭维、郑镇湖。
本规范于2011年9月首次发布，2012年6月第一次修订，2014年5月第二次修订。
3
引言
为规范我行开放平台应用开发代码，制定此规范。
4开放平台开发语言技术手册
41、范围
本文规范了Java、C/C++、C＃开发语言编码规则，主要包括命名规则、注释规则、文件结构规则和编程规则等内容。
本规范适用于软件开发中心。
本规范的使用对象为上述单位涉及使用Java、C/C++、C＃开发语言从事应用系统开发的人员。
42、规范性引用文件
无
43、术语和定义
无
44、Java开发语言
4.1Java命名规范
（1）宜使用完整的英文描述符。
（2）宜使用适用于相关领域的术语。
（3）宜使用大小写混合使名字可读。
（4）英文词不宜缩写，如果有缩写，其缩写名称宜为常用缩写，不宜自定义缩写方式，同一单词宜使用相同的表示法。
如果该英文单词没有常用缩写，请使用全称。
（5）标识符宜按其在应用中的含义由一个或多个词组成。
可以是英文词，但严禁使用中文拼音。
标识应该简洁，避免使用长的名字，不宜超过32个字母。
例子：
StringvariableUsedToStoreSystemInformation//太复杂了
StringsystemInformation//正确，简单明了
StringsysInfo//过于简单
（6）避免使用类似的名字，或仅仅是大小写不同的名字,禁止使用Java的保留字。
（7）除静态常量外，命名避免使用下划线。
（8）包的名字应由小写单词组成。
如：
java.lang
（9）类Class的名字宜由大写字母开头。
如：
Customer,Account
（10）变量
变量的名字应用一个小写字母开头，后面的单词用大写字母开头。
如：
firstName,lastName
（11）接口
采用完整的英文描述符说明接口封装，所有单词的第一个字母大写，宜以大写的“I”开头，名字后面加上后缀able，ible或者er。
如：
IContactable,IPrompter
（12）组件/部件
使用完整的英文描述说明组件的用途，末端应接上组件类型。
如：
okButton,customerList,fileMenu等
试对比下列代码：
btnCancel.Text="&Cancel"//不建议
cancelButton.Text="&Cancel"//推荐
（13）异常
通常采用字母e表示异常。
（14）实参/参数
宜使用与需要赋值的字段同样的名字：
setCounter（intsize）{
this.size=size;
}
（15）获取成员函数
宜在被访问字段名的前面加上前缀get。
如：
getFirstName（）,getLastName（）
（16）布尔型的获取成员函数
宜用单词is做前缀。
如：
isPersistent（）,isString（）
（17）设置成员函数
宜在被访问字段名的前面加上前缀set。
如：
setFirstName（）,setLastName（）,setWarpSpeed（）
publicvoidsetFirstName（StringfirstName）{
this.firstName=firstName;
}
（18）普通成员函数
采用完整的英文描述说明成员函数功能，第一个单词宜采用动词，第一个字母小写。
如：
openFile（）,addAccount（）
（19）静态常量字段
全部采用大写字母，单词之间用下划线分隔。
如：
MIN_BALANCE,DEFAULT_DATE
（20）循环计数器
宜采用字母i，j，k或者counter。
（21）数组
数组宜用下面的方式来命名，规则与变量一致。
是：
byte[]buffer;而不是：
bytebuffer[];
（22）文件名
源码文件名由它所包含的顶级class的类名（大小写敏感），加上.java后缀组成。
（除了package-info.java文件）。
（23）类型名
类型名有两种命名方式：
a、单独一个大写字母，有时后面再跟一个数字。
（例如，E、T、X、T2）。
b、像一般的class命名一样，再在最后接一个大写字母。
（例如，RequestT、FooBarT）。
4.2Java注释规范
44.2.1注释类型
（1）文档注释
描述Java的类、接口、构造器，方法，以及字段。
每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。
该注释应位于声明之前：
/**
*TheExampleclassprovides...
*/
publicclassExample{...
注意顶层的类和接口不缩进，而其成员是缩进的。
描述类和接口的文档注释的第一行（/**）不需缩进；随后的文档注释每行都缩进1格，应使星号纵向对齐。
成员，包括构造函数在内，其文档注释的第一行缩进2个空格，随后每行都缩进3个空格。
有关类、接口、变量或方法等不适合写在文档中的信息，可使用块注释或单行注释。
例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。
文档注释不应放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。
对文档核心部分或进行大量修改时，宜在修改处注释作者和时间信息。
（2）多行注释符
一些不再使用但仍可保留参考，或在调试过程中想让它暂时失效的代码，可采用多行注释/*...*/说明。
如：
/*这部分代码因为已被它之前的代码取代，由B.Gustafsson,于1999年6月4日注释掉。
如果两年之后还未使用，将其删除......
（源代码）*/
（3）单行注释
在成员函数内采用单行注释，来说明业务逻辑、代码段和暂时变量的声明。
注释符//后宜紧跟一个空格，然后是注释信息。
如：
//遵照Sarek的规定，给所有超过$1000的发货单
//打5%的折扣。
让利活动于1995年2月开始.
44.2.2注释规则
（1）类注释
宜注释类的目的，类所完成的功能。
（2）接口注释
宜注释设置接口的目的，及接口如何被使用以及如何不被使用。
（3）成员函数注释
（a）若成员变量已有说明，设置与获取成员函数可不加注释。
（b）对于普通成员函数，要求说明完成的功能，宜注释参数含义及返回值。
（c）对于普通成员函数内部控制结构，宜注释代码的功能及处理顺序等。
（4）实参/参数注释
宜注释参数含义、及其它任何约束或前提条件。
（5）字段/属性注释
宜注释字段描述。
（6）局部变量注释
局部变量如无特殊含义，可不加注释。
（7）段落
空白行：
是指javadoc中，上下两个段落之间只有上下对齐的*字符的行。
每个段落的第一行在第一个字符之前，有一个
标签，并且之后不要有任何空格。
（8）@从句
所有标准的@从句，应该按照如下的顺序添加：
@param、@return、@throws、@deprecated。
并且这四种@从句，不应该出现在一个没有描述的Javadoc块中。
当@从句无法在一行写完时，应该断行。
延续行在第一行的@字符的位置，缩进至少4个字符单位。
（9）摘要片段
每个类或者成员的javadoc，都是由一个摘要片段开始的。
这个片段非常重要。
因为它是类或者方法在使用时唯一能看到的文本说明。
主要摘要只是一个片段，应该是一个名词短语或者动词短语，而不应该是一个完整的句子。
但是它应该像一个完整的句子一样使用标点符号。
注意：
一种常见的错误是以这种形式使用javadoc：
/**@returnthecustomerID*/.这是不对的。
应该改为：
/**ReturnsthecustomerID.*/.
（10）何处应该使用Javadoc
至少，Javadoc应该应用于所有的public类、public和protected的成员变量和方法。
例外情况如下。
例外1：
方法本身已经足够说明的情况
当方法本身很显而易见时，可以不需要javadoc。
例如：
getFoo。
没有必要加上javadoc说明“Returnsthefoo”。
单元测试中的方法基本都能通过方法名，显而易见地知道方法的作用。
因此不需要增加javadoc。
注意：
有时候不应该引用此例外，来省略一些用户需要知道的信息。
例如：
getCannicalName。
当大部分代码阅读者不知道canonicalname是什么意思时，不应该省略Javadoc,认为只能写/**Returnsthecanonicalname.*/。
例外2：
重载方法
重载方法有时不需要再写Javadoc。
例外3：
可选的javadoc
一些在包外不可见的class和成员变量或方法，根据需要，也可以使用javadoc。
当一个注释用以说明这个类、变量或者方法的总体目标或行为时，可以使用Javadoc。
4.3Java结构规范
源码文件按照先后顺序，由以下几部分组成：
（1）License或者copyright声明信息。
（如果需要声明）
（2）包声明语句。
（3）import语句。
（4）class类声明（每个源码文件只能有唯一一个顶级class）。
每个部分之间应该只有一行空行作为间隔。
44.3.2版权信息
版权信息宜在Java文件的开头。
如：
/**
*Copyright（c）2011ICBC.
*Allrightreserved.
*/
不需要出现在JavaDoc的信息可包含在版权信息中。
44.3.3包的定义
package行应在import行之前，import中标准的包名应在本地的包名之前，且按照字母顺序排列。
对于Java代码中import其他的类，宜import为具体的类名，而不是importjava.io.*。
import语句应该被分为几个组，每个组之间由单行的空行隔开。
分组的顺序如下：
（1）所有的staticimport为归为一组。
（2）com.icbc.ctp包的import归为一组。
（3）使用的第三方包的引用。
每个顶级第三方包归为一组。
第三方包之间按ASCII码排序。
例如：
android,com,junit,org,sun
（4）java包归为一组。
（5）javax包归为一组。
同一组内的import语句之间不应用空行隔开。
例如：
package.stats;
importjava.ioInputStream;
importjava.ioOutputStream;
importjava.util.Observable;
importhotlava.util.Application;
44.3.4类的定义
（1）类的定义
Java的类定义不支持多继承，声明继承应使用extends关键字。
类可以实现多个接口，实现接口应用implements关键字声明。
publicclassCounterSet
extendsObservable
implementsCloneable
（2）类的成员定义区
类的成员变量定义顺序，宜是公共级别、保护级别、包一级别（没有访问修饰符），私有级别。
/**
*Packetcounters
*/
protectedint[]packets;
public的成员变量宜生成文档（JavaDoc）。
若protected、private和package定义的成员变量名字含义明确，可不加注释。
（3）每行声明变量的数量
宜一行一个声明，利于注释。
如：
intlevel;//indentationlevel
intsize;//sizeoftable
ObjectcurrentEntry;//currentlyselectedtableentry
优于：
intlevel,size;
不宜将不同类型变量的声明放在同一行。
例如：
intfoo,fooarray[];//不建议
（4）初始化
应在声明局部变量时做初始化，除非变量的初始值依赖于某些先前发生的计算。
（5）布局
一个代码块是指被包含在大括号{}中间的代码。
宜在代码块的开始处声明变量，不宜在首次用到该变量时才声明，for循环的索引变量除外。
voidmyMethod（）{
intint1=0;//beginningofmethodblock
if（condition）{
intint2=0;//beginningof"if"block
...
}
}
例外
for（inti=0;i避免声明的局部变量覆盖上一级声明的变量。
不应在内部代码块中声明相同的变量名。
如
intcount;
...
myMethod（）{
if（condition）{
intcount=0;//应避免
...
}
...
}
（6）类的构造函数和重载方法
类如果存在多个构造函数或者多个同名成员方法，宜按参数的数量，参数多的构造函数或者成员方法放在后面，这些函数应该写在一起，不应该被其他成员分开。
publicCounterSet（intsize）{
this.size=size;
}
publicCounterSet（intsize，intvalue）{
this.size=size;
this.value=value;
}
（7）类的公开方法
类的公开方法宜写注释。
/**
*Setthepacketcounters
*（suchaswhenrestoringfromadatabase）
*/
PublicfinalvoidsetArray（int[]r1,int[]r2,int[]r3,int[]r4）
throwsIllegalArgumentException{
//
//Ensurethearraysareofequalsize
//
if（r1.length!
=r2.length||r1.length!
=r3.length||r1.length!
=r4.length）{
thrownewIllegalArgumentException（"Arraysmustbeofthesamesize"）;
}
System.arraycopy（r1,0,r3,0,r1.length）;
System.arraycopy（r2,0,r4,0,r1.length）;
}
（8）类的toString方法
类宜定义自己的toString方法。
publicStringtoString（）{
StringBufferretval=newStringBuffer（"CounterSet:
"）;
for（inti=0;iretval.append（data.bytes.toString（））.append（data.packets.toString（））;
}
returnretva.toString（）;
}
（9）类的main方法
类定义中的main（）方法宜写在类的底部。
（10）只声明唯一一个顶级class
每个源码文件中应只能有一个顶级class，package-info.java文件除外。
（11）类成员顺序
类成员的顺序对代码的易读性有很大影响，但是没有一个统一正确的标准。
不同的类可能有不同的排序方式。
重要的是，每个class都要按照一定的逻辑规律排序。
当被问及时，能够解释清楚为什么这样排序。
例如，新增加的成员方法，不是简单地放在class代码最后面，按日期排序不是按逻辑排序。
4.4Java格式规范
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个空格。
除了以下几个特殊情况外，其他代码内容都需要遵守这个长度限制：
●按照行长度限制，无法实
升级会员 