用户工具

站点工具


代码规范:java代码规范

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

代码规范:java代码规范 [2016/10/16 14:53] (当前版本)
neohope 创建
行 1: 行 1:
 +===== Java代码规范 =====
 +==== 目的和意义 ====
 +在软件的生命周期中,维护的花费通常占很大的比例,且几乎所有的软件,在其整个生命周期中,开发人员和维护人员都不尽相同。编码规范可以改善软件的可读性,使程序员尽快而彻底地理解代码;同时,编码规范还可以提高程序代码的安全性和可维护性,提高软件开发的生产效率,所以,编码规范对于程序员而言至关重要。
 +
 +为使开发项目中所有的JAVA程序代码的风格保持一致,增加代码的可读性,便于维护及内部交流,使JAVA程序开发人员养成良好的编码习惯,有必要对JAVA程序的代码编码风格做统一的规范约束。
 +
 +==== 命名规则 ====
 +
 +=== JAVA源文件的命名 ===
 +JAVA源文件名必须和源文件中所定义的类的类名相同。
 +
 +=== Package的命名 ===
 +Package名的第一部分应是小写ASCII字符,并且是顶级域名之一,通常是com、edu、gov、mil、net、org或由ISO标准3166、1981定义的国家唯一标志码。Package名的后续部分由各组织内部命名规则决定,内部命名规则指定了各组件的目录名,所属部门名、项目名等。
 +我们的包名定义为:com.djhu.项目.模块名称.层次名称
 +例:
 +<sxh java;> ​
 +    package com.djhu.portal.broadcast.controller; ​
 +</​sxh>​
 +
 +=== Class/​Interface的命名 ===
 +Class名应是首字母大写的名词。命名时应该使其简洁而又具有描述性。异常类的命名,应以Exception结尾。Interface的命名规则在Class名称前加"​I"​。
 +例:
 +<sxh java;> ​
 +    public interface IUserService {
 +        …
 +    };
 +    public class UserServiceImp implement IUserService {
 +        …
 +    };
 +    public class InvalidException extends Exception {
 +        …
 +    };
 +</​sxh>​
 +
 +=== 常量的命名 ===
 +常量名的字母应全部大写,不同的单词之间通过下划线进行连接,并且名字组合应该赋予含义。
 +例:
 +<sxh java;> ​
 +    static final int MIN_WIDTH = 4;
 +    static final int MAX_WIDTH = 999;
 +</​sxh>​
 +
 +=== 变量的命名 ===
 +
 +== 普通变量 ==
 +普通变量名的首字母小写,其它每个单词的首字母大写。命名时应该使其简短而又有特定含义,简洁明了的向使用者展示其使用意图。
 +例:
 +<sxh java;> ​
 +    float  floatWidth ​ = 0.0;
 +    double doubleWidth = 0.0;
 +</​sxh>​
 +
 +== 约定变量 ==
 +所谓约定变量,是指那些使用后即可抛弃(throwaway)的临时变量。通常i、j、k、m和n代表整型变量;c、d和e代表字符型变量。
 +例:
 +<sxh java;> ​
 +    int  i = 0;
 +    char c = ‘a’;
 +</​sxh>​
 +
 +== 方法的命名 ==
 +方法名的第一个单词应是动词,并且首字母小写,其它每个单词首字母大写。
 +例:
 +<sxh java;> ​
 +//​查询类型方法名称query开头
 +Object ​ queryById(Long id);​或者Object queryByPersonId(Long personId);
 +//​判断性方法名称is头
 +    void isStringEmpty(String str);
 +   //​删除性的方法名称delete开头
 + Boolean deleteById(Long id);
 +//​新增类的方法名称 save开头
 +Boolean savePerson(Person person);
 +</​sxh>​
 +
 +== 方法参数的命名 ==
 +应该选择有意义的名称作为方法的参数名。如果可能的话,选择和需要赋值的字段一样的名字。
 +例:
 +<sxh java;> ​
 +//​这类方法务必用工具生成,不要用手动去输入,尽量保持代码的一致性
 +    void setCounter(int size) {
 +     this.size = size;
 +}
 +</​sxh> ​
 +
 +==== 样式结构注释样式 ====
 +JAVA程序有两类注释,实现行注释(implementation comments)和文档注释(document comments)。
 +
 +<code text>
 +实现注释,就是使用 /*...*/ 或 // 界定的注释。文档注释,又被称为"​doc comments"​或"​ JavaDoc注释"​,是JAVA独有的,由 /**...*/ 界定,并且文档注释可以通过JavaDoc工具转换成HTML文档。
 +</​code>​
 +
 +在注释里,应该对设计决策中重要的或者不是显而易见的地方进行说明,但应避免对意思表达已经清晰的语句进行注释。
 +
 +特别注意,频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候,考虑一下是否可以重写代码,并使其更清晰。
 +
 +=== 实现注释 ===
 +== 块注释 ==
 +块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。
 +例:
 +<sxh java;> ​
 +previousSentences;​
 +
 +    /*
 +     * Here is a block comment.
 +     */
 +    Sentences;
 +</​sxh>​
 +
 +== 单行注释 ==
 +单行注释显示在一行内,并与其后的代码具有一样的缩进层次。如果一个注释不能在一行内写完,应采用块注释。
 +例: ​  
 +<sxh java;>  ​
 +    if (condition) {
 +
 +// Handle the condition.  ​
 +...
 +    }
 +</​sxh>​
 +
 +=== 文档注释 ===
 +<code text>
 +置于/​**...*/​之中的注释称之为文档注释。
 +</​code>​
 +
 +文档注释用来描述Java的类、接口、构造器、方法以及字段(field),一个注释对应一个类、接口或成员,该注释应位于声明之前,与被声明的对象有着相同的缩进层次。
 +
 +在类的声明中,各种类、接口、变量、常量、方法之前都应该有相应注释。关于文档注释中的各种target的使用,请参考附录2关于JavaDoc。
 +
 +我们代码的文档注释必须要有作者信息、类信息、成员变量信息、函数信息说明函数的作用以及参数作用。 ​   ​
 +
 +例:
 +<sxh java;> ​
 +   /**
 +    * @author ​      ​(标明开发该类模块或接口或者方法的作者)
 + * @see          (对类的说明)
 +    * @version ​     (用于类和接口,标明该模块的版本)
 + * @deprecated ​  ​(说明某类或方法不被推荐使用,以及相应的替代类或替代方法)
 + */
 +    public class Example { 
 +    ​
 +        /**
 +         * this is variant A
 +         */
 +        int virantA = 0;
 + /**
 +    * @author ​      ​(标明开发该类模块或接口或者方法的作者)
 +    * @param ​       (用于方法和构造函数,说明方法中的某个参数)
 +    * @return ​      ​(用于方法,说明方法的返回值)
 +    * @exception ​   (用于方法,说明方法可能抛出的异常,​同@throws)
 +    * @see          (对类、属性、方法的说明,参考转向,也就是相关主题)
 +    * @since ​       (说明引进该类、方法或属性的起始版本)
 +    * @deprecated ​  ​(说明某类或方法不被推荐使用,以及相应的替代类或替代方法)
 + */
 +        public int methodA(parameterA){
 +            ...
 +        };
 +    }
 +</​sxh>​
 +
 +==== 声明 ====
 +=== 变量的声明 ===
 +声明变量时要对其进行初始化,如果是类中的变量,声明时不初始化,在构造函数中一定要初始化
 +例:
 +<sxh java;> ​
 +    int variantA;
 +    应改为:
 +    int variantA = 0;
 +    </​sxh> ​
 +
 +临时变量放在其作用域内声明
 +例:
 +<sxh java;> ​
 +    int tempA = 0;
 +    if (condition) {
 +        tempA = methodA();
 +        methodB(tempA);​
 +    }
 +</​sxh>​
 +    ​
 +应改为:
 +<sxh java;> ​
 +    if (condition) {
 +        int tempA = 0;
 +        tempA = methodA();
 +        methodB(tempA);​
 +    }
 +</​sxh>​
 +
 +声明应集中放在作用域的顶端(先定义后使用的原则)
 +例:
 +<sxh java;> ​
 +    if (condition) {
 +        int tempA = 0;
 +        tempA = methodA();
 +        int tempB = 0;
 +        tempB = methodB();
 +    }
 +</​sxh>​
 +    ​
 +应改为:
 +<sxh java;> ​
 +    if (condition) {
 +        int tempA = 0;
 +        int tempB = 0;
 +        tempA = methodA();
 +        tempB = methodB();
 +    }
 +</​sxh>​
 +
 +避免声明的局部变量覆盖上一级声明的变量
 +例:
 +<sxh java;> ​
 +    int counter = 0;
 +    if (condition) {
 +        int counter = 0;
 +        counter = methodA();
 +    }
 +</​sxh>​
 +    ​
 +应改为:
 +<sxh java;> ​
 +    int counter = 0;
 +    if (condition) {
 +        int counterTemp = 0;
 +        counterTemp = methodA();
 +    }
 +</​sxh>​
 +    ​
 +=== 类和接口的声明 ===
 +当编写类和接口时,应该遵守以下规则:
 +  * 在方法名与其参数列表之前的左括号"​("​间不要有空格
 +  * 左大括号"​{"​位于声明语句同行的末尾,并与末尾之间留有一个空格
 +  * 右大括号"​}"​另起一行,与相应的声明语句对齐。如果是一个空语句,"​}"​应紧跟在"​{"​之后
 +  * 方法与方法之间以空白行分隔
 +
 +例:
 +<sxh java;> ​
 +  /**
 +    * @author ​      ​(标明开发该类模块或接口或者方法的作者)
 + * @see          (对类的说明)
 +    * @version ​     (用于类和接口,标明该模块的版本)
 + * @deprecated ​  ​(说明某类或方法不被推荐使用,以及相应的替代类或替代方法)
 + */
 +    public class Sample extends Object {
 +        private int ivar1;
 +        private int ivar2;
 +        public Sample(int i, int j) {
 +            ivar1 = i;
 +            ivar2 = j;
 +        }
 +
 +        public int emptyMethod() {}
 +        …
 +    }
 +</​sxh> ​
 +    ​
 +==== 语句 ====
 +
 +=== 简单语句 ===
 +== 每行至多包含一条完整语句 ==
 +例:
 +<sxh java;> ​
 +    variantA++; variantB++;
 +    应改为:
 +    variantA++;
 +    variantB++;
 +</​sxh>​
 +
 +== 在没有必要的情况下,不要在return语句中使用括号 ==
 +例:
 +    return (0);
 +应改成:
 +    return 0;
 +    ​
 +=== 复合语句 ===
 +复合语句是包含在大括号中的语句序列,形如"​{ 语句 }"​,其编码应有如下基本规则:
 +  * 被括其中的语句应该比复合语句缩进一个层次
 +  * 左大括号"​{"​应位于复合语句起始行的行尾,并且空一个空格,右大括号"​}"​应另起一行并与复合语句首行对齐
 +  * 复合语句即使只有一个语句,也要有大括号作为界定
 +  * 每行至多包含一条完整语句
 +
 +== 判断语句 ==
 +例:
 +if-else语句应该具有如下格式:
 +<sxh java;> ​
 +    if (condition) {
 +        Sentences;
 +    }
 +
 +    if (condition) {
 +        Sentences;
 +    } else if (condition) {
 +        Sentences;
 +    } else {
 +        Sentences;
 +    }
 +</​sxh>​
 +
 +== 选择语句 ==
 +在选择语句中应添加 default情况,防止不可预知的情况发生。
 +当一个case在没有break语句的情况下,它将顺着往下执行。应在break语句的位置添加注释。[下面就含注释/​* falls through */]
 +例:
 +<sxh java;> ​
 +    switch (condition) {
 +    case ABC:
 +        Sentences;
 +        /* falls through */
 +    case DEF:
 +        Sentences;
 +        break;
 +
 +    case XYZ:
 +        Sentences;
 +        break;
 +
 +    default:
 +        Sentences;
 +        break;
 +    }
 +</​sxh> ​
 +
 +== 循环语句 ==
 +(要求:在用循环语句时尽量不要出现三层嵌套循环,且不要在循环中操作数据库)
 +在for语句的初始化或更新子句中,如果存在多项,各项间应用逗号隔开。同时,应避免使用三个以上子句,从而导致复杂度提高;若确实需要,可以在for循环之前放置初始化子句或在for循环末尾放置更新子句。
 +例:
 +<sxh java;> ​
 +    for (int i = 0, j = 10, k = 10, m = 50; i < j + k + m; i++, j--, k--, m--) {
 +        Sentences;
 +    }
 +</​sxh>​
 +
 +应改为:
 +<sxh java;> ​
 +    int i = 0;
 +    int j = 100;
 +    int k = 1000;
 +    int m = 500;
 +
 +    for (; i < j + k + m ;) {
 +        Sentences;
 +        i++;
 +        j--;
 +        k--;
 +        m--;
 +    }
 +</​sxh>​
 +
 +==== 功能代码的规范和要求 ====
 +=== controller层规范 ===
 +在SpringMVC 中,控制器Controller 负责处理由DispatcherServlet 分发的请求,它把用户请求的数据经过业务处理层处理之后封装成一个Model ,然后再把该Model 返回给对应的View 进行展示。
 +
 +在controller层中对service层的注入全部采用注解来实现(@Autowired)、日志生成采用slf4j工具jar
 +<sxh java;> ​
 +private Logger logger=LoggerFactory.getLogger(getClass());​
 +</​sxh> ​
 +
 +Controller中功能代码要求:
 +  * 校验:如果方法中要处理的参数需要先校验在处理时校验方法写在前面。
 +  * 必要数据处理:经校验完数据进入数据预先处理过程。
 +  * 调用相关service层
 +  * service层处理相关逻辑业务,代码块不要超过150行,如果过多要进行拆分。
 +具体详细请看spring mvc controller介绍文档
 +
 +=== service层规范 ===
 +Service层基本上是业务处理的核心模块,经常具有复杂的代码块在一个方法中,这易导致代码的可读性大大减低,给后期维护带来更多困难。
 +Service层中对dao层的注入采用配置方式这里不用注解,service自身也是采用配置bean的方式来时提供注入。日志生成采用slf4j工具jar
 +<sxh java;> ​
 +private Logger logger=LoggerFactory.getLogger(getClass());​
 +</​sxh>​
 +
 +Service中代码要求:
 +  * 1、 代码模块化开发:一个复杂的业务尽量合理分解,分解成一个单独的小功能模块代码,使用一个具体的方法(函数)来实现。在主方法中按照顺序调用这些小方法,这样做的目的是为了拆分主方法不会使得住方法中代码很庞大,也易于代码的阅读。
 +  * 2、 业务数据处理:数据处理过程也是遵循先校验在处理的原则执行。尽量避免在循环中操作数据库,循环数据处理不要出现三层循环嵌套尽量使用泛型来处理。
 +  * 3、 对于查询尽量要不在代码里面拼sql语句传到mybatis文件中,所有查询尽量写在对应的xml文件中。
 +  * 4、 事物控制:service层中事物控制采用配置方式来实现,默认事物是REQUIRED事物模式加载,如果需要事物的其他属性时可以在配置中添加,​
 +  * 5、 数据保存或返回:数据处理完以后一般是生成一个object传到dao层进行数据保存或者返回到controller层。
 +
 +=== dao层规范 ===
 +我们讨论决定采用mybatis做数据库持久层框架,据mybatis的特性,我们的dao层没有是现实类相对应。Dao自身通过配置bean来实现dao对外调用,配置方式如下:
 +namespace是表示每个mybatis文件的唯一性,所以全部都采用相对应的dao
 +
 +<sxh xml;> ​
 +<mapper namespace="​com.ats.monitor.core.dao.ApplicationBusinessDao"​ >
 +<bean id="​userDao"​ class="​org.mybatis.spring.mapper.MapperFactoryBean">​
 +  <​property name="​mapperInterface" ​  ​value="​com.ats.user.dao.UserDao"/>​
 +  <​property name="​sqlSessionFactory"​ ref="​sqlSessionFactory"/>​
 +  </​bean>​
 +</​sxh>​
 +
 +Mybatis参考文件
 +Dao层中代码要求:
 +  * 所有到都继承一个BesaDao<​Object>​类:在basedao类提供了大部分操作数据方法,如果遇到特殊调用时,可以在自己定义的dao中添加(命名一定要规范)。
 +  * Dao层不涉及业务处理,也不能出现什么逻辑代码,只有保存或查询方法。
  
代码规范/java代码规范.txt · 最后更改: 2016/10/16 14:53 由 neohope