Java编程规范：命名规定、注释规则及编程建议

Java编程规范

Java命名规定

​ Java中尽量使用完整的英文描述及适用于相关领域的术语来命名标识符。为了增加标识符的可读性，形式上要采用大小写混合方式。标识符的长度虽然没有限定，但应尽量避免使用长的名字，一般少于15个字母。另外要少用或慎用缩写，如果使用则要保证在整个应用程序中风格统一。要避免使用拼写类似的名字，或者仅仅是大小写不同的名字，并且除静态常量名称外，颖避免使用下划线。

Java中的名称包括：包（Package）、类（Class）名、接口（Interface）、变量名、方法名、常数名。Java中命名约定的基本原则如下：

1. _、$不作为变量名、方法名开头
2. 变量名、方法名首单词小写，其余单单词只有首字母大写，如anyVariableWorld
3. 接口名、类名首单词第一个字母大写
4. 常量完全大写

1. 包的命名规则
   • 包采用完整的英文描述符，应该都是由小写字母组成。对于全局包，可以将所在公司Internet域名反转再接上包名，如com.taranis.graphics
2. 类与接口的命名规则
   • 类名与接口名都采用完整的英文描述符，并且所有单词的第一个字母大写，如Customer、SavingsAccount。另外，接口名后面可以加上后缀able、ible或者er，但这不是必须的，如Contactable、Prompter
3. 变量的命名规则
   • 对类的属性（变量）、方法的参数、局部变量来说，其命名规范是采用完整的英文描述，第一个字母小写，任何中间单词的首字母大写，如firstName、lastName。
     但是，变量命名还存在着某些习惯，如：
     • 异常（Exception）通常采用字母e表示
     • 循环计数器通常采用字母i、j、k或者counter
4. 常量（static final）的命名规则
   • 常量名全部采用大写字母，单词之间用下划线分隔，如MIN_BALANCE
5. 方法的命名规则
   • 普通成员方法
     • 采用完整的英文描述说明成员方法功能，第一个单词要采用一个生动的动词，第一个字母小写，如openFile（）
   • 属性存取器方法
     • 属性存取器是类中对某个私用属性值进行读、写的方法。对于读取属性值的方法称为属性获取方法，而对属性赋值的方法称为属性设置方法
       • 属性获取方法的命名采用访问属性名的前面加上前缀get，如getFirstName（）；
       • 所有布尔型获取方法必须采用单词is做前缀，如isPersistent（）；
       • 属性设置方法的命名采用被访问字段名的前面加上前缀set，如setFirstName（）
6. 构件（Component）的命名规则
   • 构件使用完整的英文描述来说明构件的用途，末端应接上构件类型，如cancelButton

Java注释规则

​ 注释是Java程序的重要组成部分。恰当的注释增强了程序的可读性与可维护性。作注释的基本原则包括：增加代码的清晰度、简洁性、完整性

1. 三类注释的使用

   1. 文档注释/***/

      文档注释被javadoc处理，可以建立类的一个外部说明性文件。文档注释必须书写在类、域、构造方法、方法以及字段（field）定义之前，对这些定义的含义、功能等进行说明。文档注释由两部分组成–描述和块标记。例如：

      /**
      *	The doGet method of the servlet
      *	This method is called when a form has its tag value method
      *		equals to get
      *	@param request
      *	 the request send by the client to the server
      *	@param response
      *	 the response send by the server to the client
      *	@throws ServletException
      *	 if an error occurred
      *	@throws IOException
      *	 if an error occurred
      */
      public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException,IOException {
      	doPost(request,response);
      }
      

      本例中，前两行行为描述，后面由@符号起头为块标记注释。注释标签语法如下：
      @author 对类的说明，表明开发该类模块的作者

      @version 对类的说明，表明该类模块的版本

      @see 对类、属性、方法的说明、参考转向，也就是相关主题

      @param 对方法的说明，对方法中某参数的说明

      @return 对方法的说明，对方法返回值的说明

      @exception 对方法的说明，对方法可能抛出的异常进行说明

   2. 多行注释/**/
      采用C语言风格的注释，在程序中注释掉一行或多行的代码段。这种方式可以用于去掉当前不再使用但仍想保留的代码或进行条件编译标记。

   3. 单行注释//
      在成员方法内采用单行注释，说明代码段的业务逻辑、临时变量的声明等。格式上一般在注释符”//“猴必须紧跟一个空格，然后才是注释的信息。

2. 注释的使用原则

   1. 在类的声明中需要考虑注释的地方是：类的功能和用途、类的开发和维护历史
   2. 接口需要注释的地方是：接口的用途、使用环境与使用方法
   3. 属性的注释需要对属性描述。如果属性的可见性定义不是私有（private）的，应该用注释适当说明理由
   4. 成员方法注释：成员方法注释位于源代码的顶部。注释的内容包括与方法相关的所有信息，具体可以包含如下内容：
      • 成员方法的功能：说明方法的功能，使方法更容易被别人理解，增加代码的重用性
      • 成员方法参数说明：说明方法接收的参数的含义及使用方法
      • 成员方法返回值说明
      • 已知漏洞：说明成员方法中明显的问题，提示其他编程人员该成员方法的缺陷和难点。如果在一个类中这个漏洞出现在多个成员方法中，则应在类的注释中对这个漏洞加以说明
      • 成员方法抛出的异常：说明成员方法抛出的全部异常，使得调用该方法的其他编程人员知道要捕获什么，如何进行异常处理
      • 成员方法可见性说明：如果觉得其他开发人员会质疑该成员方法的可见性定义，如把一个成员方法设置为公共的（public），但没有任何对象调用它，那么就有必要说明这样定义的原因。这将有助于其他开发者对该方法的设计思想清晰地了解
      • 正确引用成员方法的一两个例子放在注释中
      • 对多线程并发控制进行必要说明：多线程并发控制问题是比较复杂的问题，应该适当对同步属性及其访问约束条件加以说明
      • 成员方法内部注释：控制结构说明、关键代码的逻辑说明、局部变量说明、难懂或复杂的代码、处理顺序说明

编程建议

1. 成员方法的30秒原则和第32条原则

   其他编程人员应该能够在30秒内阅读成员方法，并完全理解它是做什么的、为什么这么做，以及如何去做。如果不是这样，说明代码过于拘谨，不好维护，需要对其进行改进。第32条原则指的是，成员方法不要太长，一般一个成员方法体能够在一个屏幕内显示，这样的长度是合适的。

2. 最小化公共和受保护的接口
   尽量减少类中公共和受保护的接口（成员方法），是面向对象的实际的基本原则之一。这个原则的好处是：

   1. 易学性。要学习如何使用一个类，只要学习使用它的公共接口。公共接口越短，类就越好理解
   2. 减少耦合性。无论何时，一个类的实例发送消息给另一个类的实例或者直接发给这个类本身，这两个类就是耦合相关。最小化了公共接口就意味着最小化了类的耦合性。
   3. 更大的适应性。直接与耦合性相关。无论何时要改变公共接口的成员方法的实现方式，如要改变成员方法的返回值，可能不得不修改所有调用这个成员方法的代码。公共接口越短，封装性越好，因此也就有更大的适应性。

   除了最小化公共接口，也要最小化类中受保护的接口。因为父类中所有受保护的接口对子类而言实际上是公共接口。任何受保护的接口中的成员方法都可以被子类调用。因此，基于最小化公共接口同样的原因，也应当对受保护的接口最小化

3. 提高程序性能
   首先尽量不要在循环中创建和释放对象。其次在处理字符串时，尽量使用StringBuffer类。StringBuffer类是构成String类的基础。String类将StringBuffer类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当工作完成后将StringBuffer对象再转换为所需的String对象。例如，如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么应该使用StringBuffer对象和它的apend（）方法。如果使用String对象代替StringBuffer对象的话，会花费许多不必要的创建和释放对象的CPU时间。最后，避免不必要的使用关键字syncronized，这样可以减少发生死锁的几率。必须使用时，也尽量控制范围，最好在块内控制。

4. 成功编写代码的几点建议
   首先，在编写代码的过程中，应时刻意识到所编写的代码不仅要能够在及其中运行，还要使别人容易看懂。及其能够运行而别人无法理解的程序，不是好的程序。为此要尽量遵循下列原则，写干净的代码：

   • 遵守命名规范
   • 为代码写文档、注释
   • 为代码分段
   • 适当使用空白行
   • 遵循第32条规则

   其次，在编码之前做好程序的设计工作，可以大大减少以后重复修改代码的工作量，做到事倍功半。因此在真正开始编码前，花一定时间搞清楚怎样写代码，尽量保持代码的简洁易懂，并尽量从小模块开始逐渐扩大来开发