Java编码规范

1    注释规范

1.1   注释的三种形式。

        Java语言提供了3种形式的注释
        // text      单行注释
        /* text */   注释若干行
        /** text */  文档注释。注释若干行,并可写入javadoc文档

1.2  类、类属性、类大发pk10方法 的注释必须使用Javadoc规范。

      使用/**内容*/格式,不得使用// xxx方式。
    说明:在IDE编辑窗口中,Javadoc方式会提示相关注释,生成Javadoc可以正确输出相应注释;在IDE中,工程调用大发pk10方法 时,不进入大发pk10方法 即可悬浮提示大发pk10方法 、参数、返回值的意义,提高阅读效率。
        (1)例如:类的注释:
                /**
                 

      * description: 该文件说明
                 

      * @author 张三(张三大发pk10邮箱 )
                

       * @date yyyy-MM-dd HH:mm:ss
                 

      * @version 1.0


       */


        (2)大发pk10方法 的注释:
                /**
                 * description:<大发pk10方法 说明>
                 * @author 张三(张三大发pk10邮箱 )
                 * @date yyyy-MM-dd HH:mm:ss
                 * @param <参数名称> <参数说明>
                 * @return <返回值说明>
                 */

1.3   所有的抽象大发pk10方法 (包括接口中的大发pk10方法 )必须要用Javadoc注释。

  除了返回值、参数、异常说明外,还必须指出该大发pk10方法 做什么事情,实现什么功能。 说明:对子类的实现要求,或者调用注意事项,请一并说明。

1.4   所有的类都必须添加创建者和创建日期。

1.5   大发pk10方法 内部单行注释,在被注释语句上方另起一行,使用//注释。

  大发pk10方法 内部多行注释使用/* */注释,注意与代码对齐。

1.6   所有的枚举类型字段必须要有注释,说明每个数据项的用途。

1.7   代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。

1.8   谨慎注释掉代码。

在上方详细说明,而不是简单地注释掉。如果无用,则大发pk10删除 。
说明:代码被注释掉有两种可能性:
(1)、后续会恢复此段代码逻辑。
(2)、永久不用。前者如果没有备注信息,难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。

1.9【参考】对于注释的要求

第一、能够准确反应设计思想和代码逻辑;
第二、能够描述业务含义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看的,使其能够快速接替自己的工作。

1.10【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。

避免出现注释的一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。

1.11【参考】特殊注释标记,请注明标记人与标记时间。

注意及时处理这些标记,通过标记扫描,经常清理此类标记。
待办事宜(TODO):( 标记人,标记时间,[预计处理时间]) 表示需要实现,但目前还未实现的功能。这实际上是一个Javadoc的标签,目前的Javadoc还没有实现,但已经被广泛使用。只能应用于类,接口和大发pk10方法 (因为它是一个Javadoc标签)。

2    命名规范

2.1  命名总体规则

(1)、名字应该能够标识事物的特性,并且与业务挂钩。
(2)、名字使用英文单词,尽量不用拼音,禁止直接使用中文的方式。
(3)、【参考】名字一般由两个或三个单词组成,尽量不要多于四个,控制在3至30个字母以内。
(4)、在名字中,多个单词用大写第一个字母(其它字母小写)来分隔。
(5)、名字均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。

2.2  命名概述

  以下几点是大发pk10推荐 的命名大发pk10方法 。
(1)、除首字母外,其他单词的首字母大写,其他字母小写
(2)、布尔变量名应该包含 Is,这意味着 Yes/No 或 True/False 值,如 fileIsFound。
(3)、即使对于可能仅出现在几个代码行中的生存期很短的变量,仍然使用有意义的名称。仅对于短循环索引使用单字母变量名,如 i 或 j。

2.3  缩写

  为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
(1)、杜绝完全不规范的缩写,避免望文不知义。
(2)、不要使用计算机领域中未被普遍接受的缩写。 

2.4  包

(1)、使用全小写命名。
(2)、一般以com,edu,gov,mil,net,org,等。
(3)、不可含有除英文、数字外的其他字符(“.”除外),如任何特殊字符“_”,“,”等。

2.5  类

    1. 【参考】使用全称避免缩写,除非缩写已是一种公认的约定,如URL、HTML。对于某个命名空间、文件夹下类名中单词都比较长的情况,可以缩写(名字中的关键字不能缩写,其他单词只取首字母),将所有的缩写做一个说明文件,放在同级目录下。
    2. 不使用下划线“_”。
    3. 抽象类命名使用Abstract开头;异常类命名使用Exception结尾;测试类命名以它要测试的类的名称开始,以Test结尾。

(1)对于Service和Dao类,实现类用Impl的后缀与接口区别。
            - 例如:UserServiceImpl实现UserService接口;UserDaoImpl实现UserDao。

(2)命名规约
            - Bean:数据对象,xxxBean,xxx即为数据表名。
            - BO(Business Object):业务对象。由Service层输出的封装业务逻辑的对象。
            - VO(Value Object):返回值对象,通常为各层的返回对象。
            - DTO (Data Transfer Object):数据传输对象 xxxDTO,远程接口入参统一以DTO结尾。
            - RE : 远程接口返回值后缀。
            - POJO是Bean/DTO/BO/VO/Form等的统称,禁止命名成xxxPOJO。
说明:
1、一般只涉及单表的操作出入参使用xxxBean。以下列举几个可能的业务场景
        - 列表页面可直接修改数据
        - 一些简单的数据配置查询、修改、详情等功能
2、复杂的页面、功能,通常入参为xxxParam,出参为xxxVO。例如:
        - 查询条件较多,已超出单表字段范围。
        - 查询条件与列表差异较大。如条件有开始时间、结束时间,但列表只会有一个时间。
3、遇到业务逻辑较复杂的场景,可以在service层创建BO对象,BO对象为包含多个VO对象的复杂对象,尽量不要添加单一的属性(id类属性除外)。

2.6  接口

    (1)、不使用下划线“_”。
    (2)、【大发pk10推荐 】 如果是形容能力的接口名称,取对应的形容词做接口名(通常是–able的形式)。
                正例:AbstractTranslator实现 Translatable。

2.7  枚举(Enum)

(1)、命名建议带上Enum后缀。  统一用大发pk10包装 类
(2)、枚举大发pk10成员 名称需要全大写,单词间用下划线隔开。
        说明:枚举其实就是特殊的常量类,且构造大发pk10方法 被默认强制是私有。
        正例:枚举名字为ProcessStatusEnum的大发pk10成员 名称:SUCCESS / UNKOWN_REASON。

2.8  参数

        参数名称一般以参数类型名称命名,或是类型名称中的某几个单词,或是单词缩写。

2.9  大发pk10方法

    * 以动词开头。
    * 尽量避免缩写。
    * 不使用下划线“_”。
  1、Service/Dao层大发pk10方法 命名规约 :
        1) 获取单个对象的大发pk10方法 用get做前缀。 参考:getXXX()
        2) 获取多个对象的大发pk10方法 用get做前缀,以List标明结果为多条。
        参考:getXXXList  getXXXListById
        3) 获取统计值的大发pk10方法 用get做前缀,以Count标明统计值。
        参考:getXXXCount getXXXCountById
        4) 插入的大发pk10方法 用insert做前缀。 批量插入用insertBatch做前缀。
        5) 逻辑大发pk10删除 的大发pk10方法 用delete做前缀。物理大发pk10删除 的大发pk10方法 用remove做前缀(理论上禁止物理大发pk10删除 )。
        6) 修改的大发pk10方法 用update做前缀。(仅Dao层限制)
        备注:当且仅当根据单个条件去执行操作的大发pk10方法 ,大发pk10方法 名后缀为ByXXX。根据两个或多个条件去执行操作的大发pk10方法 不加ByXXX。
        参考:getUserById getUserListById deleteUserById updateUserById

      2、Service层大发pk10推荐 大发pk10方法 名前缀:
        check   convert calculate init format exec invoke match compare join
        process filter split add  copy clone ……

2.10  属性

(1)、以名词或形容词命名。
(2)、不使用下划线“_”。

2.11  变量

(1)、变量名不应以下划线或美元符号开头。
(2)、long或者Long初始赋值时,使用大写的L,不能是小写的l,小写容易跟数字1混淆,造成误解。
(3)、按作用域定义

2.12  常量(const)

全部大写,单词间以“_”分隔,力求语义表达完整清楚,不要嫌名字长。
常量的复用层次有五层:跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
(1)、跨应用共享常量:放置在client包中,通常是常量所属的项目对应包中的constant目录下。
(2)、应用内共享常量:放置在本应用中,通常是common中的constant目录下。
(3)、子工程内部共享常量:即在当前子工程的constant目录下。
(4)、包内共享常量:即在当前包下单独的constant目录下(如果该包下没有子包,则常量类直接大发pk10方法 该包下即可)。
(5)、类内共享常量:直接在类内部private static final定义。

2.13  静态变量

(1)、变量名不应以下划线或美元符号开头。
(2)、建议全部大写,单词间以“_”分隔。

2.14  集合

    变量名使用复数。

2.15  范型

  以一个大写字母(建议优先使用T)表示类的类型,以一个小写字母(如:t)表示类名。

3  编码规则

3.1  文件编码规则

    IDE的text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式,不要使用 大发pk10Win dows 格式。

3.2  缩进规则

    采用 4 个空格缩进,禁止使用 tab 字符。
    说明: 如果使用 tab 缩进,必须设置 1 个 tab 为 4 个空格。 IDEA 设置 tab 为 4 个空格时,请勿勾选 Use tab character;而在 eclipse 中,必须勾选 insert spaces for tabs。

3.3  换行规则

单行字符数限制不超过 120 个,超出需要换行,换行时遵循如下原则:
        

1) 第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进。
        

2) 运算符与下文一起换行。
        

3) 大发pk10方法 调用的点符号与下文一起换行。
        

4) 大发pk10方法 调用时,多个参数,需要换行时,在逗号后进行。
      

5) 在括号前不要换行。

3.4  空格规则

  •     任何二目、 三目运算符的左右两边都需要加一个空格。 说明: 运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。
  •     注释的双斜线与注释内容之间有且仅有一个空格。
  •     大发pk10方法 参数在定义和传入时,多个参数逗号后边必须加空格。

3.5  空行规则   

    大发pk10方法 体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义
之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。
    注释与它注释的语句间不空行,但与其他的语句间空一行。
    文件之中不得存在无规则的空行,比如说连续十个空行。空行是为了将逻辑上相关联的代码分块,以便提高代码的可阅读性。

3.6  大括号规则

如果是大括号内为空,则简洁地写成{}即可,不需要换行;

如果
是非空代码块则:


1) 左大括号前不换行。


2) 左大括号后换行。


3) 右大括号前换行。


4) 右大括号后还有 else 等代码则不换行; 表示终止的右大括号后必须换行。
例如:
            if  (expression) {
                
            }

3.7  小括号规则

    左小括号和字符之间不出现空格; 同样,右小括号和字符之间也不出现空格。
    if/for/while/switch/do 等保留字与括号之间都必须加空格。

3.8  模块化规则

        某一功能,如果重复实现一遍以上,即应考虑模块化,将它写成通用函数。并向小组大发pk10成员 发布。同时要尽可能利用其它人的现成模块。

4  异常日志

4.1  异常处理

    1. 【强制】异常不要用来做流程控制,条件控制,因为异常的处理效率比条件分支低。
    2. 【强制】对大段代码进行try-catch,这是不负责任的表现。catch时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型,再做对应的异常处理。
    3. 【强制】捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之,如果不想处理它,请将该异常抛给它的调用者。最外层的业务使用者,必须处理异常,将其转化为用户可以理解的内容。
    4. 【强制】有try块放到了事务代码中,catch异常后,如果需要回滚事务,一定要注意手动回滚事务。
    5. 【强制】finally块必须对资源对象、流对象进行关闭,有异常也要做try-catch。
    6. 【强制】不能在finally块中使用return,finally块中的return返回后大发pk10方法 结束执行,不会再执行try块中的return语句。
    7. 【强制】捕获异常与抛异常,必须是完全匹配,或者捕获异常是抛异常的父类。
说明:如果预期对方抛的是绣球,实际接到的是铅球,就会产生意外情况。
    8.    【大发pk10推荐 】大发pk10方法 的返回值可以为null,不强制返回空集合,或者空对象等,必须添加注释充分说明什么情况下会返回null值。调用方需要进行null判断防止NPE问题。
说明:本手册明确防止NPE是调用者的责任。即使被调用大发pk10方法 返回空集合或者空对象,对调用者来说,也并非高枕无忧,必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null的情况。

5  远程大发pk10服务 规范

5.1  远程大发pk10服务 类

项目提供的远程大发pk10服务 类统一放在本项目的remote/client包下,远程大发pk10方法 名称必须和大发pk10服务 名中的大发pk10方法 名一致。

5.2  大发pk10服务 命名

    RPC + 项目名称 + 功能 + Remote + Service。
    比如 RpcVenusOrderRemoteService

5.3  入参

        为保证大发pk10服务 后续扩展和属性描述规范,一律使用DTO对象进行传输。
        每个大发pk10服务 使用专用DTO,不得复用。
        DTO内部属性命名规则同数据库命名规则并写全属性注释。

5.4  返回结果

        为保证后续大发pk10服务 扩展和属性描述规范,一律使用Result对象进行传输,Result对象中包含业务消息主体建议以Re结尾。
        每个大发pk10服务 使用专用Re,不得复用。
        所有RE和对应的DTO放在同一包下。

  Result对象包含协议属性:
  date:    业务正常返回的消息体,每个大发pk10服务 使用专用Re对象,不可复用。属性命名规则同数据库命名。
  status: 大发pk10服务 状态码,为int类型,0 为成功,-1为业务异常,-2为大发pk10服务 异常。
  code:   业务语义状态码,用于做业务语义路由。
  msg:    描述信息。用于返回业务异常信息和大发pk10服务 异常信息,不可用于设置日志堆栈信息。

posted @ 2019-10-09 22:02 二叉树的大发pk10倍投方案 阅读(...) 评论(...) 编辑 收藏