九、代码注释与编码规范

——————————————————————————————————————————————————

1.代码注释与编码规范

在程序代码中适当地添加注释，可以提高程序的可读性和可维护性。好的编码规范可以使程序更易阅读和理解。

——————————————————————————————————————————————————

1.1.代码注释

通过在程序代码中添加注释可提高程序的可读性。注释中包含了程序的信息，可以帮助程序员更好地阅读和理解程序。在Java源程序文件的任意位置处都可添加注释语句。因为Java编译器不会对注释语句进行编译，所以代码中的所有注释语句都不会对程序产生任何影响。

单行注释

“//”为单行注释标记，从符号“//”开始直到换行的所有内容均作为注释而被编译器忽略。语法如下：

   //注释内容

例如：以下代码为声明的int型变量添加注释：

   int age;    //定义int型变量，用于保存年龄信息

多行注释

“/* /”为多行注释标记，符号“/”与“*/”之间的所有内容均为注释内容。注释中的内容可以换行。语法如下：

   /*
   注释内容1
   注释内容2
   ......
   */

在多行注释里可以嵌套单行注释

  /*
  程序名称：Hello world　 //开发时间：2021-03-05
  */

多行注释中不可以嵌套多行注释，以下代码是错误的：

  /*
  程序名称：Hello world
  /*　开发时间：2021-03-05；作者：张先生　*/
  */

文档注释

“/** /”为文档注释标记。符号“/**”与“/”之间的内容均为文档注释内容。当文档注释出现在声明（如类的声明、类的成员变量的声明、类的成员方法的声明等）之前时，会被Javadoc文档工具读取作为Javadoc文档内容。除注释标记不同外，文档注释的格式与多行注释的格式相同。对于初学者而言，文档注释并不是很重要，了解即可。

说明一定要养成良好的编程习惯。软件编码规范中提到“可读性第一，效率第二”，所以程序员必须在程序中添加适量的注释来提高程序的可读性和可维护性。程序中，注释要占程序代码总量的20%～50%。

——————————————————————————————————————————————————

1.2.编码规范

在学习开发的过程中要养成良好的编码习惯，规整的代码格式会为程序日后的维护工作提供极大的便利。在此对编码规则做了以下总结。

每条语句尽量单独占一行，并且每条语句都要以分号结束。

程序代码中的分号必须是在英文状态下输入的，初学者经常会将“;”写成中文状态下的“；”，此时编译器会报出Invalid Character（非法字符）这样的错误信息。

在声明变量时，尽量使每个变量单独占一行，即使有多个数据类型相同的变量，也应将其各自放置在单独的一行上，这样有助于添加注释。对于局部变量，应在声明它们的同时为它们赋予初始值。

在Java代码中，空格仅提供分隔使用，无其他含义，开发者应控制好空格的数量，不要写过多的无用空格。

为了方便日后的维护，不要使用技术性很高、难懂、易混淆的语句。因为程序的开发者与维护者可能不是同一个人，所以应尽量使用简洁、清晰的代码编写程序需要的功能。

对于关键的方法要多加注释，这样有助于阅读者了解代码的结构与设计思路。

——————————————————————————————————————————————————

代码应该写在哪？这可能是第一次学习编程的读者最大的疑惑了。Java代码的主要结构总结：

package语句要写在类文件的第一行。如果类不在任何包中，可以不写package语句。

import语句要写在类上方、package语句下方。

方法必须写在类的{ }之内。在方法的{ }内不可以创建其他方法。

类的成员变量必须定义在类的{ }之内、方法的{ }之外的位置。在方法的{ }之内定义的变量均为局部变量。

除了上面几种类型的代码，其他类型代码都应该写在某个{ }中（如代码块或方法体之内）。其他类型的代码包括局部变量、内部类等。

如果你现在无法读懂这几点总结，请不要焦虑，这里出现的很多概念、语句在后面的内容中都会重点讲解。