学习目标：掌握代码编写规范和代码注释要求。对于初学编程者，养成良好的编程习惯是非常重要的。

1、代码注释

代码的注释对编写的代码起到一个解释的作用，借助于代码注释可以让其他开发者很容易看懂你写的代码，理解代码结构，也有助于你在很长时间后，能够看懂自己写的代码。

一段没有注释的代码：

public static void main(String[] args) {
    int num1,num2,result;
    Scanner sc = new Scanner(System.in);
    System.out.println("请输入长方形的长度");
    num1 = sc.nextInt();
    System.out.println("请输入长方形的宽度");
    num2 = sc.nextInt();
    if( num1 <=0 || num2 <=0 )
    {
      System.out.println("您输入的长度和宽度小于1或等于0，程序将退出");
      System.exit(0);
    }
    result = num1 * num2;
    System.out.println("长方形的面积为:" + result);
}

虽然没有代码注释，但对Java代码有一定了解的人，看懂这段代码还是非常容易的，从语句中也能理解程序的功能和代码的作用。

再看这段没有注释的代码：

public void BobbleSort() {
   int[] arr = { 6, 3, 8, 2, 9, 1 };
   for (int num : arr) {
    System.out.print(num + " ");
   }
   for (int i = 0; i < arr.length - 1; i++) {
     for (int j = 0; j < arr.length - 1 - i; j++) {
      if (arr[j] > arr[j + 1]) {
        int temp = arr[j];
        arr[j] = arr[j + 1];
        arr[j + 1] = temp;
         }
        }
  }
  for (int num : arr) {
    System.out.print(num + " ");
  }
}

知道上面的代码啥意思吗？没有一定Java基础的人，想看懂有一定难度。不过从方法名字也可以判断出来，这是冒泡排序的算法。

下面的这段代码是不是很容易理解了呢？

public void BobbleSort() {
        //声明待排序的整型数组
        int[] arr = { 6, 3, 8, 2, 9, 1 };
        //输出排序前的数组元素
        for (int num : arr) {
            System.out.print(num + " ");
        }
        /**
         * 用for循环语句控制数组的扫描趟数,
         * 扫描趟数为待排序数组元素的个数减去1
         */
        for (int i = 0; i < arr.length - 1; i++) {
            /**
             * 用for循环遍历待排序数组元素，并进行比较和位置交换，
             * 循环范围介于0到排序数组元素的个数减去1再减去外层循环当前执行的扫描趟数
             */
            for (int j = 0; j < arr.length - 1 - i; j++) {
                //交换数组元素
                if (arr[j] > arr[j + 1]) {
                    int temp = arr[j];
                    arr[j] = arr[j + 1];
                    arr[j + 1] = temp;
                }
            }
        }
        //输出排序后的数组元素
        for (int num : arr) {
            System.out.print(num + " ");
        }
 }

代码加上注释后，就很容易看懂冒泡排序的算法了，也有助于了解冒泡排序的算法原理。

如何正确地给代码增加注释呢？下面从注释标签规范、注释基本要求、块注释、单行注释、尾端注释方面进行说明。

（1）注释标签规范

给代码加注释需要采用符合javadoc标准的注释标签语法，以便使用工具自动生成相关文档。注释标签见下表。

（2）注释基本要求

给代码添加注释是为了增加对程序的阅读理解，因此注释的内容要清楚、明了，含义准确，防止注释二义性；源代码有效注释行的数量应在程序行数量的20%以上；在class文件头部应进行注释，注释应列出：版权说明、版本号、生成日期、作者、功能描述等内容。

（3）块注释

块注释通常用于提供对文件、方法、数据结构和算法的描述。放置于每个文件以及每个方法之前，也可用于其他地方，如方法内部。功能和方法内部的块注释，应与所描述的代码具有相同的缩进格式，块注释之首应该有一个空行，用于把块注释和代码分割开来。

“/**”符号是块注释的开始，“*/”符号是块注释的结束，在注释块中，每行注释内容以“*”符号开始。

示例：

（4）单行注释

单行注释用于对语句及语句块的解释，一般放置在语句或语句块的前面。注释可显示在一行内，并与其后的代码具有相同的缩进层级。

“//”为单行注释标记，从符号“//”开始直到换行为止的所有内容都是注释内容。

单行注释也可以使用“/**/”注释标记，符号“/*”与“*/”之间的所有内容均为注释内容。

示例：

（5）尾端注释

尾端注释一般紧跟在语句的后面加以解释，与语句在同一行。但应有足够的空白分开代码和注释。

示例：

良好的代码注释有助于对程序的理解。遵循注释标签规范可以使用工具自动生成相关文档。给代码添加注释是为了增加对程序的阅读理解，因此注释的内容要清楚、明了，含义准确。对类、方法、功能的注释一般采用块注释。对语句的注释多采用单行注释。

2  编码规范

每个开发者都有自己的编程风格，有的代码写得很漂亮，结构清晰，易读易理解；有的代码写的就比较散乱，易读性不强，让人有读天书的感觉，更不用说理解了；有的代码写的错误频出，调试排错耗费太多时间。IT公司对后两种开发者都是避而远之的。Java初学者自然不想做后者，那么就从现在开始养成良好的编程风格和习惯。

命名规则

开发Java程序需要对包、类文件、方法、变量、接口进行命名。有些开发者图省心，对上面元素的命名采用拼音的方式，给代码的审查和维护带来很大麻烦。特别是在团队分工合作的项目中，因为用拼音不能见名知意，会产生很大的代码沟通障碍。所以，在开发过程中，遵循命名规则特别重要。

下面从命名的基本要求、类和接口命名、方法命名、参数与变量命名进行说明。

（1）命名基本要求

命名含义清晰、不易混淆，使用标准的英文单词或缩写，若使用特殊约定或缩写，则要有注释说明。

（2）类和接口命名

Java中的类和接口命名应以大写字母开头，其他字母都小写的英文单词组成。类应以名词或名词短语命名，并体现类的作用。接口的名称取决于接口的主要功能和用途。如果接口是使对象具有某种特定的功能，则接口的名称宜使用可描述这种功能的形容词，否则使用名词或名词短语。

（3）方法命名

类的方法命名采用大小写混合的形式，以小写字母开头，名字中其他单词的首字母以大写字母开头，所有其他的单词都为小写字母，不应使用下划线分隔单词，并且命名应描绘方法的作用和功能。

其中获取或设置类的某种属性的方法应显式的命名为 getProperty（），或setProperty（），其中property为类的属性名称。

（4）参数与变量命名

参数与变量的命名应采用大小写混合的形式，以小写字母开头，名称中其他单词或只取首字母的缩写单词要以大写字母开头，所有其他的单词均为小写字母，不应使用下划线分隔单词。

对于变量命名，禁止取单个字符（如i、j、k...），但i、j、k作局部循环变量允许使用。

程序中使用的常量和枚举需要由全部大写的多个单词组成的说明型名称，每个单词之间用下划线分隔。

编码格式要求

格式要求即代码的排版要求，规范的代码排版可以提高程序的易读性，也容易发现代码存在的问题。下面给出了具体的排版规范要求。

（1）代码行的长度

a)   单行不应超过80个字符，较长的语句要分成多行书写；

b)   if、for、do、while、case、switch、default等语句独自占一行；

c)   语句应在逗号分隔符处划分新行；

d)   表达式在操作符处划分新行，操作符放在新行之首；

e)   划分出的新行要进行适当的缩进，使排版整齐，语句可读。

（2）缩进

缩进基本要求如下：

a)   程序块要采用缩进风格编写，缩进的空格数为4个；

b)   在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。

（3）空行

相对独立的程序块之间、变量说明之后应加空行。在下列情况下应使用一个空行：

a)   在版权声明块、包声明块、引用声明块之后；

b)   在类的声明之间；

c)   在方法的声明之间；

d)   在类中声明最后一个属性之后，声明第一个方法之前。

（4）空格

在两个以上的关键字、变量、常量进行对等操作时，操作符之前、之后或前后应加空格；进行非对等操作时，如果是关系密切的立即操作符（如->）后不应加空格。应遵循以下约定：

在两个以上的关键字、变量、常量进行对等操作时，操作符之前、之后或前后应加空格。

Java类、方法、变量等的命名需要遵循见名知意的原则，并全部采用英文单词或缩写。类和接口命名应以大写字母开头，其他字母都小写的英文单词组成。类应以名词或名词短语命名，并体现类的作用。方法命名采用大小写混合的形式，以小写字母开头，名字中其他单词的首字母以大写字母开头，所有其他的单词都为小写字母，不应使用下划线分隔单词，并且命名应描绘方法的作用和功能。参数与变量的命名同方法的命名相同。

要让代码具有良好的可读性。除了注释和命名外，排版格式对提高可读性也是非常重要的。排版要点是要利用好缩进、空行和空格，让代码结构变得清晰。