java技术规范

 

1        前言

 

1.1      适用范围

 

本规范自发布之日起执行，范围涵盖熙菱信息技术有限公司软件工程事业部所有在建的软件项目和研发中的软件产品。

 

1.2      文档约定

 

我们通过“要”、“考虑”、“避免”和“不要”四个词来区分本文中不同规范的级别

 

• 要：描述的是必须遵循的规范。违反该级别的规范而又具有正当理由的情况是极其罕见的；

• 考虑：描述的是在一般情况下应该遵循的规范，但如果完全理解规范背后的道理，并有很好的理由不遵循它时，也不要畏惧打破常规；

• 不要：描述的是一些几乎绝不应该违反的规范；

• 避免：描述的做法通常不好，但却存在一些已知的可以违反该规范的情况。

 

总体上说，“要”和“不要”具有强制性质，而“考虑”和“避免”则是一些建议。

 

 

 

2        标识符命名规范

 

对标识符的命名要使用英文单词，必要时可以使用汉语拼音的全拼，严禁使用简拼来为任何标识符命名。

 

2.1      命名风格概述

 

我们主要使用PascalCasing、camelCasing和SCREAMING_CAPS三种标识符的命名风格，涵盖java、javascript、sql等编程语言。html/dhtml、xml/xsd/xslt、css等另行描述。下面分别描述这三种风格：

 

 

 

• PascalCasing风格

  • 描述：把标识符中的每个单词的首字母(包括长度为2个字符以上的首字母缩写词)大写。两个字母长的首字母缩写词是一个特例，在这种情况下两个字母都要大写。

  • 示例：

 

PropertyDescriptor

 

HtmlTag

 

IOStream

 

 

 

• camelCasing风格

  • 描述：把标识符中除了第一个单词之外的所有单词的首字母大写。

  • 示例：

 

propertyDescriptor

 

htmlTag

 

ioStream

 

 

 

• SCREAMING_CAPS风格

  • 描述：标识符中所有字母均大写，单词之间用下划线分隔。

  • 示例：

 

PROPERTY_DESCRIPTOR

 

HTML_TAG

 

IO_STREAM

 

2.2      关于首字母缩写词和单词缩写

 

1. 避免在标识符中使用首字母缩写词，除非他们是被普遍使用的，例如HTML、XML、IO等。

 

 

 

1. 不要在标识符中使用单词缩写。注意单词缩写与首字母缩写词是完全不同的，如XML是一个首字母缩写词，表示Extensible Markup Language。而单词缩写仅仅是把一个单词变短，如Number到num。

   正确：public Window getWindow();

   错误：public Window getWin();

         public Window getWnd();

 

 

 

1. Id和Ok是两个比较特殊的缩写词，可以在标识符中使用。

 

 

 

1. 在PascalCasing风格中，两个字母的首字母缩写词应该全部大写，如IOStream，超过两个字母的首字母缩写词只大写首字母，如HtmlTag。

 

2.3      关于复合词

 

1. 不要把复合词中的每个单词的首字母大写

   下表是一些常见的复合词和技术术语的拼写

 

PascalCasing风格拼写	camelCasing风格拼写	错误的拼写
BitFlag	bitFlag	Bitflag
Callback	callback	CallBack
Canceled	canceled	Cancelled
DoNot	doNot	Dont
Email	email	EMail
Endpoint	endpoint	EndPoint
FileName	fileName	Filename
Gridline	gridline	GridLine
Hashtable	hashtable	HashTable
Id	id	ID
Indexes	indexes	Indices
LogOff	logOff	LogOut
logOn	logOn	LogIn
Metadata	metadata	MetaData,metadata
Multipanel	multipanel	MultiPanel
Multiview	multiview	MultiView
Namespace	namespace	NameSpace
Ok	ok	OK
Pi	pi	PI
Placeholder	placeholder	PlaceHolder
SignIn	singIn	SignOn
SignOut	singOut	SignOff
UserName	userName	Username
WhiteSpace	whiteSpace	Whitespace
Writable	writable	Writeable

 

2.4      java命名规范

 

2.4.1   包

 

1. 要给java中的包赋予全小写字母的名字，哪怕是两个单词也不要用任何形式的分隔。为了遵循这一标准，请在为包命名时尽量用一个单词描述包

 

正确：java.usergroup

 

错误：java.userGroup

 

 

 

1. 系统中的包路径设计要遵循如下规范：

 

• 第一级为固化的行业、产品线或者公司名，如数据管理产品的顶级包名为data、而公安行业项目的顶级包名为police

• 第二级为产品名称或项目名称，如数据管理产品线中的多维分析二级包名为data.analysis、公安行业的数据采集项目可以为police.dataimport

• 第三级包名为逻辑分层的名称，以多维分析为例：

 

data.analysis.domain    实体层

 

data.analysis.service   服务层

 

data.analysis.controller 页面后台

 

data.analysis.vo vo层

 

 

 

1. 可根据具体用途扩展三级或四级包名，但顶级和二级包名应该是固定的。

2. 在客服系统的开发中，要新建的包都在cn.qtone.callcenter下建立

 

 

 

2.4.2   类型

 

1. 要使用PascalCasing风格的标识符来为java中的类型命名，包括类、枚举、接口和注解。

 

正确：public class RuleBuilder() {}

 

      public interface RuleBuilder() {}

 

错误：public class ruleBuilder() {}

 

 

 

1. 不要在接口前加I前缀，某些具有C#或其他编程模型(主要是COM)技术背景的程序员喜欢在接口前加以I前缀。

 

正确：public interface RuleBuilder() {}

 

错误：public interface IRuleBuilder() {}

 

 

 

1. 考虑给类型命名时使用名词

 

 

 

1. 考虑给抽象基类添加Abstract前缀，一个完整的继承层次应该具有如下的结构(更多信息可参考java的容器实现)：

 

接口：DataSeracher

 

抽象基类：AbstractDataSearcher

 

实现类：DataSearcherHibernateImpl

 

        DataSearcherIbitsImpl

 

 

 

1. 避免引入太一般的类型名，比如Element、Node、Log和Message。这些名字很可能在常用的场景中引起类型冲突，应该给这些一般化的类型名加上修饰语(FormElement、XmlNode、EventLog和SoapMessage)。

 

 

 

1. 避免给类型起会与java核心包或广泛使用的第三方包冲突的名字，比如srping中广泛使用的JdbcTemplate、hibernate中的SessionFactory等。

 

2.4.3   方法

 

1. 要使用camelCasing风格的标识符为java中的方法命名。

 

正确：public void execute() {}

 

错误：public void Execute() {}

 

 

 

1. 要给方法使用动词或动词词组的名词

 

2.4.4   成员变量

 

1. 要使用camelCasing风格的标识符为java中的成员变量命名

 

 

 

1. 不要给成员变量添加下划线或m_ 前缀

   正确：private String name;

   错误：private String _name;

         private String m_name;

 

 

 

1. 不要在给成员变量命名时使用匈牙利表示法(给变量加上代表类型的简写前缀)

 

正确：private String name;

 

错误：private String strName;

 

2.4.5   局部变量

 

局部变量的命名规范同成员变量，应该遵循如下两条基本规范：

 

1. 要使用camelCasing风格的标识符为java中的成员变量命名

 

 

 

1. 不要在给成员变量命名时使用匈牙利表示法(给变量加上代表类型的简写前缀)

 

2.4.6   常量

 

1. java中的常量即定义在类上的静态公有成员，一般不建议直接暴露成员变量，出于惯例的原因，一旦要使用常量，应该使用SCREAMING_CAPS风格为常量命名。

 

正确：public final static int MAX_NUMBER = 1000;

 

错误：public final static int maxNumber = 1000;

 

2.4.7   参数

 

1. 要在给参数命名时使用camelCasing风格

 

 

 

1. 要使用具有描述性的参数名

 

 

 

1. 考虑根据参数的意思而不是参数的类型来命名参数，这样就能更好的利用参数名来描述语义，而不是描述类型。偶尔使用基于类型的参数名是可以的，但是在采用这些规范时再回到匈牙利命名法是绝对不应该的

 

2.4.8   资源名称

 

1. 资源名称的命名规范同包的命名规范，即所有字母全小写，用点(.)分隔。

 

正确：platform.validation.name=example

 

      platform.username=admin

 

错误：platform.Validation.Name=example

 

      platform.userName=admin

 

2.5      注释的排版

 

/**

 * An example for comment formatting.

 */

package mypackage ;

 

/**

 * This is the comment for the example interface.

 */

interface Example

{

    // This is a long comment that should be split in multiple line comments in

    // case the line comment formatting is enabled

    int foo3() ;

 

    /*

     *

     * These possibilities include: <ul><li>Formatting of header

     * comments.</li><li>Formatting of Javadoc tags</li></ul>

     */

 

    int foo4() ;

 

    /**

     *

     * These possibilities include:

     * <ul>

     * <li>Formatting of header comments.</li>

     * <li>Formatting of Javadoc tags</li>

     * </ul>

     */

 

    int bar() ;

 

    /*

     *

     * These possibilities include: <ul><li>Formatting of header

     * comments.</li><li>Formatting of Javadoc tags</li></ul>

     */

    int bar2() ; // This is a long comment that should be split in multiple line

              // comments in case the line comment formatting is enabled

 

    int foo2() ;

 

    /**

     * The following is some sample code which illustrates source formatting

     * within javadoc comments:

     *

     * <pre>

     * public class Example

     * {

     *     final int a = 1 ;

     *     final boolean b = true ;

     * }

     * </pre>

     *

     * Descriptions of parameters and return values are best appended at end of

     * the javadoc comment.

     *

     * @param a

     *            The first parameter. For an optimum result, this should be an

     *            odd number between 0 and 100.

     * @param b

     *            The second parameter.

     * @return The result of the foo operation, usually within 0 and 1000.

     */

    int foo( int a, int b ) ;

}

 

 

 

 

 

3         注释规范

 

1. 编码中除私有的成员变量或方法外，都要求加上javadoc风格的注释，下述所有注释规范是强制性的，因为公有和保护的成员或方法上注释用来生成API文档。

 

3.1      类型注释

 

/**

 * <p>说明性文字，可以使用Html标签来进行排版。</p>

 * <p>不同段落间用p标签来分隔。</p>

*

 * @author作者

 */

 

3.2      方法注释

 

/**

 * <p>说明性文字，可以使用Html标签来进行排版。</p>

 * @param groupName 组名称

 * @param key 键

 * @return值

 */

public Object get( String groupName, Object key ) ;

 

3.3      常量注释

 

/**

 * 每次从数据库取数据数

 */

publicstaticfinalintDATA_MAX = 1000 ;

 

4        公共API设计规范

 

1. 公共API的命名尽量少使用技术术语，例如：一个打印作业提交的类应该是Printer，而不是PrinterQueue。因为该场景的用户关心的是提交打印作业，而不关心其内部是否是一个队列实现。

 

5        惯例及约定

 

5.1       服务类的命名约定

 

1. 要使用如下的命名方式对Service类进行命名：项目前缀+类名+Service后缀

 

例如：平台的User服务类名称应该为：PlatformUserService

 

      分析平台的查询对象服务类应该为：AnalysisMetadataService

 

 

 

1. 在使用spring管理Service类时，bean的名称应该为类名的首字母小写(即类名的camelCasing风格拼写)

 

例如：PlatformUserService的bean名称应该是platformUserSerivce

 

      AnalysisMetadataService的bean名称应该是analysisMetadataService

 

 

 

1. 要将服务类放在service包下，如平台的服务类应该在data.platform.service包下。

 

5.2      SpringMVC中Controller类的命名约定

 

1. 要使用如下的命名策略来为Controller类进行命名，项目前缀+类名+Controller

 

例如：平台User的控制器类应该是：PlatformUserController

 

      分析平台的查询对象服务类应该是：AnalysisMetadataController

 

 

 

1. 在使用spring管理Controller类时，bean的名称应该为类名的首字母小写(即类名的camelCasing风格拼写)

 

例如：PlatformUserController的bean名称应该是platformUserController

 

      AnalysisMetadataController的bean名称应该是analysisMetadataController

 

 

 

1. 要将服务类放在controller包下，如平台的服务类应该在data.platform.controller包下。

    

   5.3数据库设计约定

2. 表命名规则：应用名_模块名_表名. 客服系统的表命名CC_表名

3. 表主键命名：主键统一使用id命名