推荐编码开发规范精品.docx

资源描述

推荐编码开发规范精品.docx

《推荐编码开发规范精品.docx》由会员分享，可在线阅读，更多相关《推荐编码开发规范精品.docx（20页珍藏版）》请在冰豆网上搜索。

推荐编码开发规范精品.docx

推荐编码开发规范精品

编码规范说明书

中海集运滞期费管理信息系统

中海集运

文档编号：

生效日期：

密级：

版本：

R1.0

编制：

审核：

Nopartofthispublicationmaybecopiedwithouttheexpresswritten

PermissionofGillionTechnologiesLtd.

修订历史

Date

Revision

Description

Author

20XX-01-04

R1.0

Create

林华

导言

1.1.编写目的

本规范的目的是为了使海丰集运项目开发小组能以标准的、规范的方式进行编码。

通过该规范的学习，以使开发人员养成良好的编码风格和习惯，并以此形成开发小组编码约定，提高程序的可靠性、可读性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。

1.2.内容边界

结合项目实际开发情况和Java基础语法知识,主要针对声明、命名、注释、代码组织与风格、性能和安全等方面进行规范和说明。

1.3.术语及缩写

全称

含义

1.4.文档结构

1.5.参考文档

资料名称

位置

2.声明

总体描述

声明的基本原则是遵守Java语言规范，并遵从项目习惯用法。

2.1.包

在导入包时当完全限制代码所有的类的名字，尽量少用通配符的方式，但导入一些通用包，或用到一个包下大部分类时，则可使用通配符方式,如：

例如:

importorg.apachemons.beanutils.PropertyUtils;

importjava.util.*;

同意个包中的类的导入时当声明在一起，可由编辑器自动完成功能。

Eclipse采用ctrl+shift+O导入包

2.2.类、接口

类、接口定义语法规范：

[可见性][（'abstract'|'final'）][Class|Interface]class_name[（'extends'|'implements'）][父类或接口名]{}

例如：

publicclassFuelSaveAwardByGradeViewextendsmonDataView{}

其中:

abstract类——含抽象方法的类，不能实例化，但允许继承他的子类实例化,只能单继承。

final类——最终类，设计十分完美的类，不能有子类，不能在继承的类。

2.3.方法

良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：

尽量限制成员函数

的可见性。

如果成员函数没必要公有（public），就定义为保护（protected）；没必要保护

（protected），就定义为私有（private）。

方法定义语法规范：

[可见性][（'abstract'|'final'）]['synchronized'][返回值类型]method_name（参数

列表）[（'throws'）][异常列表]{

//功能模块

}

例如：

publicListgetAllUserList（）throwsDAOException{}

2.4.字段

字段定义语法规范：

[（‘public’|’private’|’protected’）]（‘final’|’volatile’）][‘static’][‘transient’]

data_typefield_name[‘=’expression]‘;’

例如：

privatestringstrUserName=’TOM’;

2.5.代码示例

package.sitc.rpt.rcp.viewpart;

importjava.math.BigDecimal;

importjava.util.ArrayList;

importjava.util.List;

importjava.util.Map;

/**

*@authorsuzx

*@create_date20XX-01-01

*@view_name耗油/船速查询（按月份）

publicclassFindConsumptionByMonthViewextendsBaseView{

publicstaticfinalStringID="ful.FindConsumptionByMonthView";//--常量

protectedstaticStringname="love";//---实例变量

publicStringuserCode="sh12345";//--公有字段

protectedfloatprice=（float）1.0;//--受保护字段

privateintcount;//--私有字段

//公共方法

publicvoidgetUserName（）{

}

//受保护方法---------------------------------------------

protectedvoidconvert（）{

}

//私有方法-----------------------------------------------

privatevoidgetUserCode（）{

}

3.命名

总体描述

规范的命名能使程序更易阅读，从而更易于理解。

它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。

3.1.包与类命名

3.1.1.包命名

海丰集运项目开发的应用包命名要求带有前缀.sitc，采用“.sitc.模块名.rcp.子功能包名”的形式，如“.sitc.mkt.rcp.viewpart”。

包名和子功能包名要求具有实际的意义，从单词或缩写上能够看出包的意义。

例如：

3.1.2.类命名

（1）类名首字母应该大写,之后连接的单词第一个字母大写，既所谓的驼峰法

（2）类名要求不要过长，一般控制在30个字符以内

（3）项目针对查询页面，编辑页面，弹出页面,报表等页面进一步做了一些规定:

1.查询页面:

Find+实体名+View或者Find+功能名+View

例如:

FindMarketAreaView营销区查询

FindOnScheduleStatisticsView准班率查询

2.编辑或者查询带编辑页面:

Edit+功能名+实体+View

例如:

Edit+MarketAreaView

3.弹出框编辑页面:

功能+实体+Dialog

例如:

SelectCustomerDialog

3.1.3.Entity对象命名

项目架构通过Hibernate映射数据库，所以涉及实体的命名，该部分通过ER图直接生成，所以相对规范,具体参考:

<<海丰集运数据库设计开发规范.doc>>

例如：

FuelSaveAward,FuelType,VoyagePartition…

3.1.4.Service命名

Service层主要负责处理系统的业务逻辑，一个主要的实体对应一个Service，关于这个主要实体的操作都集中在Service里面，主要涉及对象的粒度来定义一个接口和一个到多个实现。

该部分通过工具直接生成，所以相对规范。

示例：

UserService,UserServiceImpl

1.Service接口命名规范为：

对象名+Service

2.Service实现命名规范为：

对象名+Service+Impl

3.1.5.DAO命名

现在的框架不需要开发人员自己写DAO代码，DAO已经统一成monDAO和monDAOHibernateImpl,如果碰到特许情况需要自己开发DAO的时候，按照以下规则：

例如：

UserDAOHibernateImpl,UserDAOJDOImpl,UserDAOCMPImpl…

1.DAO接口命名规范为：

对象名+DAO

2.DAO实现命名规范为：

对象名+DAO+具体的O/R实现框架+Impl

3.1.6.Exception命名

异常类名一般由表示异常类型的单词和Exception组成，并且第一个字母大写。

如:

ActionException。

逻辑名称+Exception

3.2.属性命名

Java中成员变量又称成员属性，它是描述对象状态的数据，是类中很重要的组成成分，成员变量是定义在类里面，并和方法处于同一层次。

3.2.1.成员变量和参数命名

类的成员变量和在方法中所声明的局部变量即参数都是用户标识符，它们的命名规则相同，语法结构都是：

[变量修饰符]类型说明符变量名例如：

privateintnLen;

1.[变量修饰符]：

修饰符声明了成员变量的访问权限，分别是：

私有（private）、保护（protected）和公共（public）。

除此之外，还有一种默认的访问权限。

类型说明符：

类型可以是Java中的任意数据类型，包括基本类型、数组、类和接口。

变量名：

第一个字母小写，之后连接的单词第一个字母大写，如果是简写的单词全部大写。

2.静态成员变量：

变量前加上static标识符例如：

protectedstaticintstat=0;

3.静态变量的另一个用途是定义静态常量：

publicstaticdoublePI=3.1415926;

简单数据类型规范表：

数据类型

变量名前缀

例子

boolean

bCustomExist,baCustomExist

char

cSymbol,caSymbols

byte

yByte,yaBytes

short

sHour,saHours

int

nLen,nLoopCounter,naLength

long

lMemory,laTimes

float

fLength,faLength

double

dMile,daMiles

Integer

int

intQuantity

String

str

strVesselName

BigDecimal

big

bigPrice

Date

dtStart

注：

byte与int类型的前缀较特殊，使用时应注意

3.2.2.常量命名

常量在运行过程中是不可改变的，一般通过finalstatic来修饰,static用来修饰属性时称为静态属性，不属于某个具体的对象，属于类，但是所有的对象都能对其进行修改，单个final修饰的属性并不是常量，final表示的是不可改变性，但是属于某个具体的对象，两个加起来就是一个属于类并且不可改变的属性，即常量。

包括：

a.整型常量123，b.实型常量3.123，c.字符常量‘a’，d.逻辑常量true,false，e.字符串常量“abcd”。

常量命名：

全部大写，相连的单词中间以”_”分开

例如：

publicstaticfinalintDEFAULT_PAGE_SIZE=1;

privatestaticfinalStringSTR_WORLD="Helloworld!

3.2.3.项目中控件/组件命名

控件类型

gfa4j控件类

前缀

例子

CheckButton

ChkButton

chk

chkActive

RadionButton

monButton

rad

radCity

mondButton

monButton

btn

btnExit

mondialog

monDialog

dlg

dlgSltOffice

Label

monLabel

lbl

lblCode

Text（Text）

monText

txt

txtName

Text（Date）

DateText

txt

txtETD

Text（Long）

NumberText

txt

txtLength

Text（BigDecimal）

FloatNumberText

txt

txtRate

AutoSelectbo

cbo

cboCountry

SelectmonCode

scc

sccEmpNo

List

lst

lstPlace

Tree

tre

treCondition

Table

monTable

tbl

tblCustomer

TableColumn

col

colPlaceCode

TableItem

UdtTableItem

tblItm

ToolBar

monToolBar

tlb

tlbSave

ToolItem

monToolItem

tolItm

MenuItem

mnu

Grid

GridTable

grt

grdCustomer

DatePick

DatePickerbo

dtp

DatePick（Time）

DateTimePickerbo

dtp

GridLayout

gdLy

FillLayout

filLy

RowLayout

rowLy

FormLayout

frmLy

BordLayout

brdLy

FlowLayout

flwLy

posite

cmp

Group

grp

TabFolder

tab

TabItem

tabItm

Scrollposite

scmp

Group

monGroup

grp

　Field

fld

Editposite

ecp

Queryposite

qcmp

MapAutoSelectbo

mapCbo

SearchToolBar

stlb

SelectText

slt

GridData

grd

针对查询区域中的控件，建议加上Srh，例如：

lblSrhUserName，txtSrhUserName，目的是为了区分查询区的控件还是编辑区的控件。

3.3.方法命名

方法的命名采用完整的英文描述，大小写混合使用，第一个单词采用动词，并且小写开头，其他单词第一个字母大写。

语法格式：

[访问性修饰符][非访问性修饰符]返回值方法名（）

3.3.1.Entity类中方法命名

Entity是一个典型的值Bean，所以方法一般情况下只有以下两种:

例如:

get+属性名

set+属性名

3.3.2.Service类中方法命名

因为XxxServiceImpl都是对XxxService的实现，所以XxxServiceImpl的方法命名和XxxService的方法命名一致。

◆添加：

add+对象名。

◆修改：

update+对象名

◆删除：

remove+对象名

◆典型查询：

query+对象名

◆特殊查询：

find+对象名+By+条件名

◆验证方法：

validate+自定义标识

3.3.3.项目中的方法命名

◆创建组件/部件：

create+事件名

◆初始化功能（如组件监听器、service等）：

init+事件名

◆执行操作（如执行删除按钮操作）：

do+动宾+事件名,如doSaveCustomer，doDeleteCustomer

◆有返回值的：

get+事件名,如getCustomerName

◆创建按钮权限

createFunc+事件名,如createFunc

3.4.ER实体命名和表名

如果存在多表关联的情况，建议子表（第二层）=主表+Item ,从表（第三层）=主表+Detl

例如：

主表:

RepairRate 子表:

RepairRateItem 从表:

RepairRateDetl

如果表名太长采用:

主表的缩写，缩写不超过4位，具体规则：

多个单词组合的缩写取每个单词的首字母或头两个字母组成，同样不超过4个字符；

例如：

application_function=AF（1:

1）

application_function=APFU（2:

2）

application_function_role=APFR（2:

1）

application_function_role_banana=AFRB（1:

1）

4.注释

总体描述

程序中的注释是程序设计者与程序阅读者之间通信的重要手段。

应用注释规范对于软件本身和软件开发人员而言尤为重要。

并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。

好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。

好的注释规范可以最大限度的提高团队开发的合作效率。

4.1.类、接口注释

在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、创建日期和修改记录有必要时还可以对继承的父类、实现的接口、实现的算法等进行注释。

例如：

/**

类或接口描述

*燃油航次分摊计算

*@authorguxg

*@version1.0${date}

4.2.方法注释

依据标准JavaDoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。

参数注释时当注明其取值范围等

返回值当注释出失败、错误、异常时的返回情况。

异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常

例如：

/**

*计算天数间隔

*计算两个日期的天数间隔，永远返回正数或者零。

*@param时间一

*@param时间二

*@return时间间隔的天数

4.3.其它注释

应对重要的变量加以注释，以说明其含义等。

应对不易理解的分支条件表达式加注释。

不易理解的循环，应说明出口条件。

过长的方法实现，应将其语句按实现的功能分段加以概括性说明。

对于异常处理当注明正常情况及异常情况或者条件，并说明当异常发生时程序当如何处理。

针对这类情况的注释直接采用:

//时间交叉判断

4.4.常用JavaDoc标记

标签

说明

JDK1.1doclet

标准doclet

标签类型

@author作者

作者标识

√

包、类、接口

@version版本号

版本号

√

包、类、接口

@param参数名描述

方法的入参名及描述信息，如入参有特别要求，可在此注释。

√

构造函数、方法

@return描述

对函数返回值的注释

√

方法

@deprecated过期文本

标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。

√

包、类、接口、值域、构造函数、方法

@throws异常类名

构造函数或方法所会抛出的异常。

√

构造函数、方法

@exception异常类名

同@throws。

√

构造函数、方法

@see引用

查看相关内容，如类、方法、变量等。

√

包、类、接口、值域、构造函数、方法

@since描述文本

API在什么程序的什么版本后开发支持。

√

包、类、接口、值域、构造函数、方法

{@link包.类#成员标签}

链接到某个特定的成员对应的文档中。

√

包、类、接口、值域、构造函数、方法

{@value}

当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。

√（JDK1.4）

静态值域

5.代码组织与风格

总体描述

代码的组织和风格的基本原则是：

便于自己的开发，易于与他人的交流,Eclipse采用Ctrl+Shift+F格式化。

5.1.缩进

子功能块当在其父功能块后缩进。

当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。

代码中以TAB（4个字符）缩进，在编辑器中请将TAB设置为以空格替代，否则在不同编辑器

或设置下会导致TAB长度不等而影响整个程序代码的格式。

注：

eclipse中用空格（space）代替制表符（tab）的设置步骤

窗口（windows）->首选项（preferences...），在左边选Java->代码样式（codestyle）->格式化程序（Formatter），右边点“显示（show）”按钮，选“缩进（Indentation）”选项卡，在“常规设置

（generalsettings）”里的“跳格策略（Tabpolicy）”下拉列表选“仅空格（Spacesonly）”。

5.2.长度

为便于阅读和理解，单个函数的有效代码长度当尽量控制在300行以内（不包括注释行），当一个功能模块过大时往往造成阅读困难，因此当使用子函数等将相应功能抽取出来，这也有利于提高代码的重用度，尽量避免使用大类和长方法。

5.3.行宽

页宽应该设置为100字符。

一般不要超过这个宽度,这会导致在某些机器中无法以一屏来完整显示,但这一设置也可以灵活调整。

在任何情况下,超长的语句应该在一个逗号后或一个操作符前折行。

一条语句折行后,应该比原来的语句再缩进一个TAB或4个空格，以便于阅读。

5.4.间隔

类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行；

操作符两端应当各空一个字符以增加可读性；

相应独立的功能模块之间可使用注释行间隔，并标明相应内容。

5.5.括号

{}中的语句应该单独作为一行，左括号"{"当紧跟其语句后，右括号"}"永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。

较长的方法以及类、接口等的右括号后应使用//end...等标识其结束。

如:

类的结束符：

}//EOCClassName，

方法结束符：

}//endmethodName（），

功能块结束：

}//endif...userNameisnull?

循环快结束：

}//endfor...everyuser

展开阅读全文

推荐编码开发规范 精品.docx

推荐编码开发规范精品.docx