【JAVA】java coding规范

个人整合了一些开发中常见的规范，仅供参考。

• 源码文件编码应为UTF-8。

• 任何需要转义字符串表示的字符（例如\b, \t, \n, \f, \r, \’, \等），采用这种转义字符串的方式表示。

• 整个源码文件中最上面的部分应该有以下四块内容，且每个部分之间以一行空行分隔。

  • 1.License或者copyright声明信息。
  • 2.包声明语句，且包声明没有长度限制，单行长度限制规范，不适用于包声明。
  • 3.import语句，而且不应使用通配符import。所有静态导入（static import）为一组，非静态导入为一组。如果同时存在静态导入与非静态导入，则以一个空白行分隔。
  • 4.class类声明，每个源码文件中只能有一个顶级class。类成员顺序要有逻辑性。当一个类有多个构造函数或多个同名的方法时，这个函数要写在一些，中间不要有其它代码。

• 格式规范上面，可以整合在format里面。对于语句块的规范，如下。

  • 1.大括号前没有换行。
  • 2.开头大括号后换行。
  • 3.结束大括号前换行。
  • 4.如果右括号结束一个语句块或者函数体、构造函数体或者有命名的类体，则需要换行。例如，当右括号后面接else或者逗号时，不应该换行。
  • 5.一个空的语句块，可以在大括号开始之后真接接结束大括号，中间不需要空格或换行。但是当一个由几个语句块联合组成的语句块时，则需要换行。（例如：if/else 或try/catch/finally）
  • 6.对于语句块的缩进，每当一个新的语句块产生，缩进就增加两个空格。当这个语句块结束时，缩进恢复到上一层级的缩进格数。缩进要求对整个语句块中的代码和注释都适用。
  • 7.每句代码的结束都需要换行。
  • 8.Java代码的单行限制长度为100个字符。除以下情况，超出此上限的行必须进行换行。设置“Line Wrapping”，修改其下的“Maximum line width”的数值。
  • 9.当断行之后，在第一行之后的行，我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。当原行之后有多个延续行的情况，缩进可以大于4个字符。如果多个延续行之间由同样的语法元素断行，它们可以采用相同的缩进。
  -

• 对于代码的水平空白，有如下的情况。

  • 1.所有保留的关键字与紧接它之后的位于同一行的左括号之间需要用空格隔开。（例如if、for、catch）
  • 2.所有保留的关键字与在它之前的右花括号之间需要空格隔开。（例如else、catch）
  • 3.逗号、冒号、分号和右括号之后，需要空格隔开。
  • 4.// 双斜线开始一行注释时。双斜线两边都应该用空格隔开。并且可使用多个空格，但是不做强制要求。
  • 5.变量声明时，变量类型和变量名之间需要用空格隔开。
  • 6.初始化一个数组时，花括号之间可以用空格隔开，也可以不使用。（例如：new int[] {5, 6} 和 new int[] { 5, 6 } 都可以）

• 对于变量处理，有如下的情况。

  • 1.不要采用一个声明，声明多个变量。例如 int a, b；。
  • 2.局部变量不应该习惯性地放在语句块的开始处声明，而应该尽量离它第一次使用的地方最近的地方声明，以减小它们的使用范围。
  • 3.局部变量应该在声明的时候就进行初始化。如果不能在声明时初始化，也应该尽快完成初始化。

• 多行注释时，如果你希望集成开发环境能自动对齐注释，你应该使用 /**/， //一般不会自动对齐。

• long 值整型常量使用大写L后缀，从来没有小写（避免与数字1混淆）。例如：3000000000L而非3000000000l。

• 命名相关的规范。

  • 1.包名全部用小写字母，通过 . 将各级连在一起。不应该使用下划线。如com.example.deepspace。
  • 2.类型的命名，采用以大写字母开头的大小写字符间隔的方式（UpperCamelCase）。测试类的命名，应该以它所测试的类的名字为开头，并在最后加上Test结尾。例如：HashTest 、 HashIntegrationTest。
  • 3.方法命名一般使用动词或者动词短语，采用以小写字母开头的大小写字符间隔的方式（lowerCamelCase）。
  • 4.在JUnit的测试方法中，可以使用下划线，用来区分测试逻辑的名字，经常使用如下的结构：test_。例如：testPop_emptyStack 。
  • 5.常量一般使用名词或者名词短语命名。全部使用大写字符，词与词之间用下划线隔开。（CONSTANCE_CASE）。
  • 6.非常量的成员变量命名（包括静态变量和非静态变量），采用lowerCamelCase命名。一般使用名词或名词短语。
  • 7.参数命名采用lowerCamelCase命名。应该避免使用一个字符等作为参数的命名方式。
  • 8.局部变量采用lowerCamelCase命名。它相对于其他类型的命名，可以采用更简短宽松的方式。
  • 9.即使局部变量是final、不可改变的，它也不能被认为是常量，也不应该采用常量的命名方式去命名。
  • 10.类型名可以有两种命名方式：一.单独一个大写字母，有时后面再跟一个数字。（例如，E、T、X、T2）。二.像一般的class命名一样（见5.2.2节），再在最后接一个大写字母。（例如，RequestT、FooBarT）。

• 最佳实践。

  • 1.包名全部用小写字母，通过 . 将各级连在一起。不应该使用下划线。如com.example.deepspace。
  • 2.一般情况下，catch住的异常不应该被忽略，而是都需要做适当的处理。例如将错误日志打印出来，或者如果认为这种异常不会发生，则应该作为断言异常重新抛出。如果这个catch住的异常确实不需要任何处理，也应该通过注释做出说明。
  • 3.当一个静态成员被访问时，应该通过class名去访问，而不应该使用这个class的具体实例对象。
  • 4.尽可能少用甚至不使用Finalizers 方法。

• 针对 javadoc。

  • 1.注释的通用格式：当javadoc块只有一行时，可以使用单行格式来替代通用格式。
  • 2.空白行：是指javadoc中，上下两个段落之间只有上下对齐的 * 字符的行。每个段落的第一行在第一个字符之前，有一个标签，并且之后不要有任何空格。
  • 3.@从句：所有标准的@从句，应该按照如下的顺序添加：@param、@return、@throws、@deprecated。并且这四种@从句，不应该出现在一个没有描述的Javadoc块中。当@从句无法在一行写完时，应该断行。延续行在第一行的@字符的位置，缩进至少4个字符单位。
  • 4.摘要片段：主要摘要只是一个片段，应该是一个名词短语或者动词短语，而不应该是一个完整的句子。但是它应该像一个完整的句子一样使用标点符号。一种常见的错误是以这种形式使用javadoc：/* @return the customer ID /.这是不对的。应该改为：/* Returns the customer ID. /。

• 针对 哪些地方不使用javadoc。

  • 1.当方法本身很显而易见时，可以不需要javadoc。例如：getFoo。没有必要加上javadoc说明“Returns the foo”。
  • 2.重载方法有时不需要再写Javadoc。
  • 3.一些在包外不可见的class和成员变量或方法，根据需要，也可以使用javadoc。
  • 4.当一个注释用以说明这个类、变量或者方法的总体目标或行为时，该注释应使用Javadoc（使用/**）