Java代码规范和一些常见问题

   本文中的代码规范，是Java标准代码规范中的一小部分，在我看来，是最重要的一部分。

   理想目标：不需要写注释，不需要和别人介绍，别人就知道你的项目大致是做什么的，每个类大概实现了什么功能。

一.目的

     一致性、快速阅读和理解

    后期维护、提高工作效率

    团队协作

二.代码命名一般原则

在JAVA代码中，所有的代码命名的总原则是：

    1. 用标准的尽可能无歧义的全英文单词命名的方式，准确地描述变量、属性、类等。

      如：使用firstName, grandTotal等命名，就比x1,y1,fn等更容易让人理解其含义，尽管它们的长度要大一些。

      

    2. 采用一些更加准确的术语来命名。例如，如果我们的用户称他们的clients为customers，那么我们就应该采用customer来命名，而不是采用client来命名。这是一些细微的地方，但也希望能注意。

    3. 采用大小写混合的方式来命名，以便命名有很好的可读性。在JAVA代码中，将采用如下原则：类或接口命名中每个单词的首字母均大写，而单词的剩余部分均小写。其它像变量、成员方法、属性等除第一个单词全部小写以外，其它单词的首字母均大写，而单词的剩余部分均小写。

     比如，productDao.

    4. 尽量少用单词的缩写形式，但如果一定要用，则必须要选择大家通用的缩写方式，并且要在本JAVA源代码中坚持用它，而不要一会用这种缩写方式，一会用那种缩写方式。比如，如果要用“number”的缩写方式，则可用“no”或“num”两种缩写方式，而不要用“nu”这种大家不常用的缩写方式，并且要保持不变。

    5. 尽量避免太长的命名，一般以少于20个字符为宜。

        一般都不会超过。

    6. 尽量避免使用这样的命名：两个或多个命名仅仅是其中的有些字符大小写不一样，或者仅仅是其中有些单词是单复数之区别。例如：persistentObject 与 persistentObjects;  anSqlDatabase 与 anSQLDatabase等。

    7. 尽量避免使用下划线。

      在JAVA中，一般比较少的采用下划线的命名方式。

   8.函数用动词，类名、属性名等用名词。

      public class Product{}

       比如，public void add();

三、代码注释使用的一般原则和类型

在JAVA代码中，我们经常要使用代码注释的方式来帮助理解代码的含义。

代码注释的一般原则主要有以下几个方面：

1．代码中的注释应该以让人一目了然为目标。

我们之所以要增加代码注释，其目的就是为了让编写代码的人、同一项目组的成员或以后的开发人员能很容易的理解其代码的意图。

2．避免使用标语式的、实际毫无用处的代码注释。

3．尽量采用简洁、易懂的注释代码，而不要长篇大论。

4．注释哪些部分：类的目的（即类所完成的功能）、设置接口的目的以及应如何被使用、

成员方法注释（对于设置与获取成员方法，在成员变量已有说明的情况下，可以不加注释；普通成员方法要求说明完成什么功能，参数含义是什么？返回什么？）

普通成员方法内部注释（控制结构、代码做了些什么以及为什么这样做，处理顺序等）

实参和形参的含义以及其他任何约束或前提条件、字段或属性描述。

而对于局部变量，如无特别意义的情况下不加注释。

四、约定由于配置

     只需要看名字，就知道代码，大致是做什么的，不需要任何人任何的解释说明。

    1.项目名称：front，backend，mobile

    2.包名称和结构

      控制层：com.companyName.front.controller

      业务逻辑/服务层: com.companyName.front.service

      数据访问层/持久层: com.companyName.front.dao

      模型：com.companyName.front.model, domain,bean

      工具类：*.util

      拦截器：*.interceptor

   3.类的名称 

      模型：Product（标准的无歧义的英文单词）

      控制器：*Controller，ProductController

      服务：*Service，ProductService

      持久层：*Dao，ProductDao (ProductDAO，ProductMapper)

   4.配置文件

      Mybatis配置文件：

            ProductDao.xml （ProductMapper.xml）

            mybatis-config.xml

      Spring配置文件：

          spring-mvc-servlet.xml

          spring-dataSource.xml

    属性文件

         log4j.properties

         redis.properties

         mail.properties

         

              

          

常见问题

        1.函数名称不能准确地表达函数的作用。

        

          saveSkirt，saveTrouser

2. 名称用单数，而不是复数。

     

   如果要用复数，所有的都用复数。

3.名字有歧义。

   做的功能是，“用户意见反馈”，实际命名用的是“投诉”。
   
  

   

4.命名不统一。

   

 5. 名字不恰当。

  5.1 service层的代码，强调的是“对外的接口”。

   而insert更侧重于数据库mysql的插入。

   service层用add和save，比insert更恰当。

      
函数代码，表达的是增加1条“收藏” ，因此也可以用有“收藏”含义的动词，比如collect。

5.2withdraw，经常用的含义是“银行提现、资金提现”，没有“退货”的意思。

  

  

  5.3函数想表达的含义是，“构造一个查询对象”，buildCriteria更准确。

    

    一般的set方法，肯定会有 参数，并且没有返回值。

   比如：

   public void setTitle(String title){

        this.title = title;

   }

 6. 方法名不简洁。

    在WithdrawService中的save方法，默认就应该是存储Withdraw对象。

    同理，ProductService中的save方法，默认就是保存商品。

    不需要带上多余的词汇。

  

7.作用域过大

   根本不会被外部方法调用，却使用了public。

  

  8.代码重复，难以维护

   如果一段代码，出现了第2次，那么出现第3次的可能性高达99%...

   方式一：提取工具方法到工具类

    

   方式二：抽象流程、抽象接口

   方式三：拦截器

   比如：登录拦截、权限检查

 值得探讨的几个问题

1.代码行数

  

   1个函数写了100多行。

    Controller层的代码，一般都比较简单，调用Service层的接口，包装下数据，就到页面展示了。

    如果代码过大，应该把“逻辑上一起的，完成某个功能的”代码，提取成私有的方法。

    类似：

    

最后的建议：单一职责

    1个类、1个函数、1个变量，只完成1件事。

    如果不能一句话，几个单词，描述1个函数，1个变量，通常来说，是没有想清楚要做的事情。