C02-AD-0102 设计规范（NCV6编码规范）-精品文档资料整理.docx

《C02-AD-0102 设计规范（NCV6编码规范）-精品文档资料整理.docx》由会员分享，可在线阅读，更多相关《C02-AD-0102 设计规范（NCV6编码规范）-精品文档资料整理.docx（16页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、NC6.0编码规范1. 介绍22.文件和目录31.12.1 NC目录结构31.22.2 一般命名原则41.32.3 多语资源41.42.4 属性文件41.52.5 XML和组件配置文件43.JAVA代码规范51.63.1 命名规范51.6.13.1.1 一般性规则51.6.23.1.2 常量命名51.6.33.1.3变量命名51.6.43.1.4方法命名61.6.53.1.5类和接口的命名61.6.63.1.7包的命名61.6.73.1.8 接口设计规范71.73.2 注释规范91.7.13.2.1 一般性规则91.7.23.2.2 注释分类101.7.33.2.3 类/接口注释111.7.4

2、3.2.4变量注释121.7.53.2.5 方法注释121.7.63.2.6 算法注释131.7.73.2.7 修改记录134.编码规范131.84.1基本原则131.94.2类编写规范141.104.3变量151.114.4方法161.124.5 语言使用及书写规范161.134.6 测试用例161. 介绍软件开发涉及到各方面人员的交互、协作，为了有效地进行项目开发的沟通，完善代码的维护和交付，有必要在一个小组中采用统一的软件开发标准。一般来说，制定这样的标准有下列好处： 方便软件维护。据统计，80的软件开发费用在维护，规范化的代码才方便维护，降低维护成本。 在软件的整个生命期内，期望一个编

3、码人员从开始到该软件报废一致维护其代码是不现实的，必然需要不断地交付、协同 好的编码规范能够大大增强代码的可读性，便于开发人员快速的理解新代码。 任何产品都需要好的包装。我们可以把代码本身看作是一种产品，那么按照规范编程也是对这个“产品”的包装 规范化的代码也是软件质量的保证手段之一，也是软件过程能够流畅的基础。我们每个人必须牢牢树立这样的观念：无论从时间跨度还是从工作量来说，一个软件系统生存期的大部分是维护，不是开发。你今天所编写的代码，会一直使用很多年，并且很有可能被其他人维护和改进。所以，我们必须努力写出“干净”和易读的代码。本文档适用于软件开发过程中开发人员，主要包括编码人员、测试人员

4、，开发人员，规范必须严格遵守，否则程序被视为不合格程序。注：本规范中加黑加下划线部分是强制执行规范，请严格遵守。2.文件和目录1.1 2.1 NC目录结构 ierp: 所有产品共用的一些全局配置文件存放目录 webapps: NC产品的主web应用部署目录 hotwebs: NC产品的扩展web应用存放目录 ejb: NC中间件jar包存放目录 ejbXMLs：NC中间件ejb描述文件存放目录 scripts: 数据库脚本存放目录 nclogs: 系统日志存放目录 external,lib,framework,middleware客户化基础技术平台提供的一些jar包 langlib: 多语ja

5、r包 ierp/bin: 与整个产品相关的配置文件都存放在该目录,如日志配置文件logger-confing.properties modules: 各产品模块的部署目录n : 某个模块的目录，模块名必须是小写的英文字母，在能表达意义的基础上尽量的短n /META-INF/module.xml: 必须存在，配置模块的一些通用属性，如名称，描述，classloader等，注意名称必须与模块名称同名n /lib: 模块公开的API类，如接口，接口相关的VO等，放JAR包n /classes:模块公开的API类，如接口，接口相关的VO等，放带目录的.class文件等，用于补丁n /META-INF/

6、lib: 模块私有的代码，如DMO, 业务实现等,放JAR包n /META-INF/classes:模块私有的代码,放带目录的.class文件等，用于补丁n /extension/lib,classes: 用于二次扩展的公开的APIn /extension/META-INF/lib,classes:用于二次扩展的私有的APIn /client/lib,classes: 用于从目标上来说不属于公共的API,但是客户端用到的代码n / config:产品模块自己的配置文件 webappsnc_webimages :NC产品模块的图像文件 lib， classes, external/lib, cl

7、asses: 由平台维护和提供的类库，不允许第三方调整1.2 2.2 一般命名原则 文件、目录命名不能用中文，推荐使用数字和英文字母构成，只能使用数字和英文字母，不能以数字开头 文件、目录命名需要有一定的意义，尽量简短，名称符合各种主流操作系统的要求,如不要使用空格，不以”.”开头，不使用过长的文件名 文件名称的分隔，使用下划线或者采用首单词小写，其余单词首字母大写的方式分隔1.3 2.3 多语资源 多语资源文件的中文简体字符集必须用GBK编码，繁体及其他必须用UTF-16编码，英文是UTF-8 多语资源可以以JAR包形式存放在NC_HOME下的langlib目录下，JAR包名称必须以_lan

8、gres.jar结尾，或以目录方式存在NC_HOME的resources下 多语资源的结构组织如下:lang/语种编码/多语类别/多语资源文件，语种编码参考ierp/bin/langConfig.xml文件，如simpchn1.4 2.4 属性文件 最好采用UTF-8编码 文件后缀为.properties 属性文件放在各产品模块的resources目录下，按照一定目录层次进行组织1.5 2.5 XML和组件配置文件 最好使用UTF-8编码 一般的XML文件以xml作为后缀 每个模块都必须在META-INF下配置module.xml文件，用来控制改模块的一些全局特性 所有的组件配置文件都是XML

9、文件，他的后缀名必须为，upm，存放在模块的META-INF module.xml的name属性必须与模块的目录名称保持一致，他们都要求小写3.Java代码规范1.6 3.1 命名规范 1.6.1 3.1.1 一般性规则 字符集在26个英文字母、0到9的阿拉伯数字和下划线之中。Java中类、字段、方法、变量、常量尽量用字母表达，没有特别的理由不能用任何的其他字符 命名需要有一定的意义，推荐采用问题域中的术语命名，使命名在一定程度上是自描述的 命名尽量的短，如果命名太长，可以采用别名的方式，或者缩写来简化命名。缩写一定要有的意义，而且需要在整个项目中维护这些缩写的意义 名称缩写的规则（对于类名、

10、字段名、变量名称、模块名称等适用）1） 删除所有的原音字母，压缩重复字母。如button,缩写为btn，2） 如发生命名冲突，则在某一缩写中保留原音。如batton,为了不与button冲突，缩写为batn 不要用前导下划线，也不要在命名的末尾用下划线1.6.2 3.1.2 常量命名 所有的字符都必须大写。采用有意义的单词组合表达，单词与单词之间以“_”下划线隔开。 命名尽量简短，不要超过16个字符程序开发中最好不要直接对literal进行工作，最好引入常量方式应用；只有在特别的情况下才能使用， 如在for循环中初始化变量时可直接用-1,0,1这些常量。例：public final int M

11、AX_SIZE = 120;public final int MAX_WIDTH = 100;public final String PROPERTY_NAME= menu ;1.6.3 3.1.3变量命名变量的命名包括实例变量，静态变量，函数参数的命名。 避免在命名中采用数字，除非命名意义明确，程序更加清晰，对实例变量的命名中不应该有数字 变量名称是名词意义 采用有符合问题域意义的单词或单词组合。第一个单词全部小写，后续的每个单词采用首字母大写，其余小写(特殊单词除外，如URL) 命名尽量简短，不要超过16个字符 除了生命周期很短的临时变量外，避免采用单字符作为变量名，实例变量的命名不要用单

12、字符。常用的单字符变量如整型用 i、j、 k、 m、 n字符型用c、d、 e，坐标用x、y、z1.6.4 3.1.4方法命名命名多数为动词结构 采用有符合问题域意义的单词或单词组合。第一个单词采用小写，后续的每个单词采用首字母大写，其余小写（特殊字除外如URL），没有特别理由不用下划线作为分隔符 在Java中对属性方法命名遵循JavaBean的标准：1） getter方法：get+属性名, 对boolean型采用is+属性名，有些特定的属性名用has, can代替is可能更好2） setter方法：set+属性名 构造方法的命名与类名一致 如：String getName();string i

13、sStopped();void connect();1.6.5 3.1.5类和接口的命名 采用有符合问题域意义的单词或单词组合，每个单词的首字母大写，其余字母小写（特殊字除外如URL） 接口的第一个字符采用 对接口的默认实现类命名方式为接口名称去掉I, 加 Impl 产品业务的内部逻辑实现类，以BO结尾 数据访问的类以DAO或者DMO结尾 测试用例以Test结尾 对与继承ValueObject对象的类，以VO结尾例：public class Fiugrepublic interface FiugreContainerpublic class StdFigure /std为Standard的缩写

14、1.6.6 3.1.7包的命名 采用逻辑上的层次结构，从而减少依赖 产品模块内部的接口定义放在nc.itf.模块名.xx 产品模块对外定义的接口定义包：nc.pubitf.模块名.xx 服务的实现类nc.impl.模块名.xx 产品模块对外定义的接口实现包：nc.pubimpl.模块名.xx 后台业务类代码nc.bs.xx 值对象命名：nc.vo.模块名 UI层命名:nc.ui.模块名 命名简短，采用缩写 包名所有字符都为小写 不要用java, javax作为自定义包的前缀 产品开发中的类不允许放在缺省包下1.6.7 3.1.8 接口设计规范一、 名词描述：a) 接口设计：指将本业务需要给其他

15、业务提供的服务方法和进行远程调用的方法提取为接口的设计方式；b) 接口：指上述设计所涉及的类，包括接口类及接口方法中所使用的业务对象（如VO）和业务异常。不包括接口类的具体实现类；c) 代码设计：指代码即为设计文档，要求其注释可生成JavaDoc文件；d) 设计阶段：分为总体设计、详细设计；二、 设计要求：a) 设计工具：采用Eclipse直接进行代码设计；b) 文档格式：JavaDoc文档，文档中包含接口中使用的接口类、业务对象和业务异常的描述；c) JavaDoc注释要求：符合标准JavaDoc文档所要求的输写规范，具体写发详见JDK DOC帮助文件。对具体对象要求如下：i. 接口类：1.

16、 类注释：类注释应该在import语句的后面在类声明的前面；/* * （接口类简要描绘，必须以句号为结束）. * * 提供者：（提供业务组） * * 使用者：（使用业务组，若分方法描述可省略此项） * * 设计状态：（指出接口类设计阶段：总体、详细） * * version（接口版本） * author （接口类总设计负责人） */2. 方法注释：方法注释要紧靠方法的前面；/* * （接口方法简要描述，必须以句号为结束）. * * 调用模块： * （明确指出本接口适用范围：公共、私有或具体应用业务模块）* * 最后修改人： * * 最后修改日前： * * 用例描述： * * param（参数用

17、途描述） * return（返回值描述） * throws（异常描述） * since（开始使用的NC版本） * see（关联类） */ii. 业务对象类：1. 类注释/* * （业务对象类简要描绘，必须以句号为结束）. * * 拥有者：（拥有业务对象的业务组） * * 设计状态：（指出接口类设计阶段：总体、详细） * * version （业务对象版本） * author （作者/最后修改人） * since （开始使用的NC版本） */2. get方法注释/* * （属性简要描述，必须以句号为结束）. * return */3. set方法注释/* * （属性简要描述，必须以句号为结束）.

18、 * param （参数用途描述） */iii. 业务异常类：1. 类注释/* * （业务异常类简要描绘，必须以句号为结束）. * * 拥有者：（拥有异常的业务组） * * 设计状态：（指出接口类设计阶段：总体、详细） * * version（业务异常类版本） * author （作者/最后修改人） * since （开始使用的NC版本） * see （关联类） */2. 构造方法注释/* * （异常构造的简要描述，必须以句号为结束）. */d) 不同设计阶段要求：i. 总体设计：明确描述接口类名称和用途，接口方法名称和用途；ii. 详细设计：明确描述接口方法参数和返回值，明确描述方法使用的业

19、务对象和异常，明确描述接口方法用例；三、 应用实例a) 接口类：nc.itf.uap.test.ITestBServiceb) 业务对象类：nc.vo.uap.test.BusinessVOc) 业务异常类：nc.bs.uap.test.BusinessExceptiond) 生成的JavaDoc文件1.7 3.2 注释规范1.7.1 3.2.1 一般性规则 注释应该使代码更加清晰易懂 注释要简单明了，只要提供能够明确理解程序所必要的信息就可以了。如果注释太复杂说明程序需要修改调整，使设计更加合理。 注释不仅描述程序做了什么， 还要描述为什么要这样做,以及约束 对于一般的getter、sett

20、er方法不用注释 注释不能嵌套 生成开发文档的需要用中文编写1.7.2 3.2.2 注释分类 文档注释 /* */可以对用多行，一般用来对类、接口、成员方法、成员变量、静态字段、静态方法、常量进行说明。Javadoc可以用它来产生代码的文档。为了可读性，可以有缩进和格式控制。文档注释常采用一些标签进行文档的特定用途描述,用于帮助Javadoc产生文档,常用的有：标签Used for目的author name类/接口描述代码的作者，每个作者对应一个这样的标签deprecated类成员方法说明该段API已经被废除exception name description 或 throws name de

21、scription成员方法描述方法抛出的异常每个异常一个对应一个这样的标签param name description 成员方法描述成员方法中的参数用途和意义，一个参数对应一个这样的标签return description成员方法描述成员方法的返回值的意义since 类/接口成员方法描述该段API开始的时间see ClassName类/接口成员方法成员变量用于引用特定的类描述，一般ClassName用包括包名的全名see ClassName#memberfunction类/接口成员方法成员变量用于引用特定的类的成员方法的描述，一般ClassName用包括包名的全名version text类/接

22、口版本inheritDoc类/接口成员方法继承的文档 行注释/一次只能注释一行，一般用来简短的描述某一个局部变量，程序块的作用。 块注释： /* */可以用多行，一般用来对程序块、算法实现、类的实现进行说明。为了可读性，可以有缩进和格式控制。一般在行注释不能满足注释需要的时候采用。一般用来作为文件头、复杂算法的说明，方法体内的复杂过程说明等1.7.3 3.2.3 类/接口注释类/接口描述，一般比较详细。按照常用的说明顺序排列，主要包括 通常都需要发布为API文档，因此通常采用文档注释 类的主要说明，以。或.结束 类设计的目标，完成什么样的功能 主要的类使用如何使用该类, 包括环境要求,如是否线

23、程安全,并发性要求, 以及使用约束 已知的BUG 描述类的修改历史:修改人+日期简单说明 author作者、version版本, see参照,since开始版本等信息如： 版本就以当时开发的产品的应用版本号为准/* * This class provides default implementations for the JFC Action * interface. Standard behaviors like the get and set methods for * Action object properties (icon, text, and enabled) are defin

24、ed * here. The developer need only subclass this abstract class and * define the actionPerformed method. * * Warning: * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is appropriate * for short term storage or RMI between appli

25、cations running the same * version of Swing. A future release of Swing will provide support for * long term persistence. * * version 1.41 02/02/00 * author Georges Saab * see Action */为了使形成的文档可读性好，注释中经常带有缩进和格式控制。类描述放在类的类定义的紧前面，不能有任何的空行。1.7.4 3.2.4变量注释 成员变量、类静态变量采用文档注释，对成员变量的注释通常包括：1） 变量的意义2） 变量的合法值域

26、3） 对并发访问的限制如: /* Web.xml文件中configServlet参数的UIAPP.xml initparam */ public final static String APP_CONFIG = aaa.uiapp; 局部变量，如算法相关的变量采用块或行注释如：void func() int i; /用于循环计数 参数变量注释一般用文档注释,并且用param来说明为参数,一般包括:1） 参数的用途2） 对参数值范围的要求1.7.5 3.2.5 方法注释描述函数的功能，对成员方法，静态方法一般采用文档描述，特别是公开的方法。注释可以很详细，为了可读性强也可包含格式控制，如下面说明

27、含有缩进：/* Here is a method comment with some very special* formatting that I want indent(1) to ignore.*/方法注释一般包括: 方法的主要说明，以。或.结束 描述方法完成什么样的功能,方法的目标,用该方法的原因 描述方法的使用方法,包括使用的环境要求,如前置条件,后置条件和并发性要求 描述已知的bug 描述方法的修改历史：修改人+日期简单说明 () param c elements to be inserted into this list.（参数说明） return true if this li

28、st changed as a result of the call.(返回值说明) throws NullPointerException if the specified Collection is null.（异常说明） see如果重载方法必须参考父类的方法 Eclips下采用Alt+Shift+J生成Javadoc说明方法的放回值(return)1.7.6 3.2.6 算法注释算法描述指在实现级别的描述注释，如在方法内的注释，对类实现的注释,这样使得程序更加易懂,方便程序算法的修改和BUG的修复。一般采用块/行注释，对于简短的描述采用行注释，不要用文档注释。注释的主要内容包括： 某些局

29、部变量的意义和用途 复杂的控制结构的注释，如循环，分枝，条件表达式。说明控制所要达到的目标 复杂的代码段的描述，说明代码完成的功能，以及为什么这样做。1.7.7 3.2.7 修改记录修改记录放在类的文件头说明中，一般为 + + + 。4.编码规范1.8 4.1基本原则 一个程序文件最好不要超过行 尽可能缩小对象的作用域，这样对象的可见范围和生存期也都会尽可能地小 一个方法所完成的功能要单一,不同的功能封装为不同的方法 尽可能的处理异常或转换异常，不要一味的包装异常 不允许调用System.gc 如果对象在某个特定范围内必须被清理（而不是作为垃圾被回收），请使用带有finally子句的try块，

30、在finally子句中进行清理。 对于把一些逻辑相关的类组织在一起，可以考虑把一个类的定义放在另一个类的定义中，这种情况推荐使用内部类（比如界面层中的事件响应等）。内部类拥有所有外围类所有成员的访问权。 对成员变量的访问最好通过getter/setter方法,这样能够保证访问的合法性,以及代码调整 优先选择接口而不是抽象类或具体类。如果你知道某些东西将成为基类，你应当优先把它们设计成接口；只有在必须放进方法定义或成员变量时，才把它修改为具体或抽象类。接口只和客户希望的动作有关（协议），而类则倾向于关注实现细节 使用java标准库提供的容器。精通他们的用法，将极大地提高工作效率。优先选择Arra

31、yList来处理顺序结构，选择HashSet来处理集合，选择HashMap来处理关联数组，选择linkedList来处理堆栈和队列，它对顺序访问进行了优化，向List中间插入与删除的开销小，但随机访问则较慢。当使用前三个的时候，应该把他们向上转型为List、Set和Map,这样就可以在必要的时候以其它方式实现 使用这些标准的容器时，强制使用泛型的形式 数组是一种效率最高的存储和随机访问对象引用序列的方式，但是当创建了一个数组对象，数组的大小就被固定了，如果在空间不足时再创建新的数组进行复制，这样效率就比ArrayList开销大了。所以必须明确使用场景 尽量使用”private”、”protec

32、ted”关键字。一旦你把库的特征（包括类、方法、字段）标记为public,你就再也不可能去掉他们。在这种方式下，实现的变动对派生类造成的影响最小，在处理多线程问题的时候，保持私有性尤其重要，因为只有Private的字段才会受到保护，而不用担心被未受同步控制的使用所破坏。 尽量的使用泛型支持 采用类而不是对象引用静态变量和方法 UFDobule常量必须使用UFDouble.ZERO, UFDouble.ONE 使用UFBoolean必须采用UFBoolean.valueof(true|false|y|n|Y|N)，的形式进行构造，常量必须用UFBoolean.TRUE, UFBoolean.FA

33、LSE 禁止后台业务代码使用如下代码trysomething()catch(Exception ex)new Exception()1.9 4.2类编写规范 类的结构组织，一般按照如下的顺序：1 常量声明2 静态变量声明3 成员变量声明4 构造函数部分5 Finalize部分6 成员方法部分7 静态方法部分这种顺序是推荐的，在实际开发中可以按照一定的尺度修改，原则是程序更易读。如对方法的排序按照重要性，或按照字母顺序排列或按照方法之间的关系排列。每个方法（包括构造与finalize）都是一个段。多个变量声明按照逻辑共同组成一个段，段与段之间以空行分隔。类声明时，要指出其访问控制，一般为没有修饰

34、符，public，和private。方法与方法之间，大的部分之间都需要以空行隔离。编写通用性的类时，请遵守标准形式。包括定义equals()、hasCode()、toString()、Clone(实现Cloneable接口)，并实现Comparable和Serialiable接口对于设计期间不需要继承的类，尽量使用final1.10 4.3变量 对成员变量, 尽量采用private 每一个变量声明/定义占一行（参数变量除外），如： int a;int b;比int a,b; 更容易读, 更容易查找bug 局部变量在使用前必须初始化，一般在声明时初始化 变量的声明要放在程序块的开始位置如：voi

35、d myMethod() int int1 = 0; / beginning of method blockif (condition) int int2 = 0; / beginning of if block.一种例外情况是在for语句中，定义声明不仅不占一行，还在表达式内部，完全采用Eclips生成,如：for(int i = 0; i100; i+) 数组的申明采用 方式如：char buffer; 而不是： char buffer;1.11 4.4方法 对成员方法,不要轻易的采用public的成员变量。主要的修饰符有public, private, protected, 无 空方法中

36、方法声明和函数体可都在一行。如：void func() 方法和方法之间空一行 方法的文档注释放在方法的紧前面，不能空一行。 避免过多的参数列表，尽量控制在个以内，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性 方法中的循环潜套不能超过层 对于设计期间不需要子类来重载的类，尽量使用final 每个方法尽量代码行数尽量不要超过100行（有效代码行，不包括注释），但必须保证逻辑的完整性1.12 4.5 语言使用及书写规范 避免变量的定义与上一层作用域的变量同名。 方法与方法之间用需要用一空行隔开 局部变量在使用时刻声明，局部变量/静态变量在声明时同时初始化 在与常数作比较时常数放在比较表达式的前面如：if(“simpleCase”.equals(obj)if(null = obj). return语句中，不要有复杂的运算。 switch语句，需要一个缺省的分支 在Eclipse中最好进行代码格式化1.13 4.6 测试用例 测试用例采用JUnit框架进行编写 测试用例的类以Test结尾 对于核心功能测试用例必须覆盖(何冠宇copyright)16 / 16