【Java/代码风格】编程风格规范

  前几天在gitbook上翻到Google的[Java代码编程风格规范](https://legacy.gitbook.com/book/jervyshi/google-java-styleguide-zh/details)，花了些时间阅读，觉得非常有收获。 本着好记性不如烂笔头的老生常谈，我将其中常用部分内容摘录出来做成笔记，以备后查。

---

一、准确的命名标识符

 1.对所有标识符都通用的规则

  标识符只能使用ASCII字母和数字因此每个有效的标识符名称都能匹配正则表达式\w+。 在Google其它编程语言风格中使用的特殊前缀或后缀，如name_, mName, s_name和kName，在Java编程风格中都不再使用。

 2.标识符类型的规则

  2.1包名

    包名全部小写，连续的单词只是简单地连接起来，不使用下划线

类名

   类名都以UpperCamelCase风格编写，通常是名词或名词短语；接口名称有时可能是形容词或形容词短语。
    测试类的命名以它要测试的类的名称开始，以Test结束。例如，HashTest或HashIntegrationTest。

  2.2方法名

    方法名都以lowerCamelCase风格编写,，通常是动词或动词短语；下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是：test<MethodUnderTest>_<state>，例如testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法。

  2.3常量名

    常量名命名模式为CONSTANT_CASE，全部字母大写，用下划线分隔单词，通常是名词或名词短语。

    每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时， 考虑它是否真的感觉像是一个常量。例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。 只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。

  // Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(',');  // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

  2.4非常量字段名

    非常量字段名以lowerCamelCase风格编写。这些名字通常是名词或名词短语。

  2.5参数名

    参数名以lowerCamelCase风格编写，参数应该避免用单个字符命名。

  2.6局部变量名

    局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。
    虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。
    即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。

  2.7类型变量名

    类型变量可用以下两种风格之一进行命名：

  a)单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)。
  b)以类命名方式，后面加个大写的T(如：RequestT, FooBarT)。

  2.8驼峰式命名法(CamelCase)

    驼峰式命名法分大驼峰式命名法(UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。 有时，我们有不只一种合理的方式将一个英语词组转换成驼峰形式，如缩略语或不寻常的结构(例如”IPv6”或”iOS”)。
Google指定了以下的转换方案，名字从散文形式(prose form)开始:

1. 把短语转换为纯ASCII码，并且移除任何单引号。例如：”Müller’s algorithm”将变成”Muellers algorithm”。

2. 把这个结果切分成单词，在空格或其它标点符号(通常是连字符)处分割开。
   推荐：如果某个单词已经有了常用的驼峰表示形式，按它的组成将它分割开(如”AdWords”将分割成”ad words”)。 需要注意的是”iOS”并不是一个真正的驼峰表示形式，因此该推荐对它并不适用。

3. 现在将所有字母都小写(包括缩写)，然后将单词的第一个字母大写：
   每个单词的第一个字母都大写，来得到大驼峰式命名。
   除了第一个单词，每个单词的第一个字母都大写，来得到小驼峰式命名。

4. 最后将所有的单词连接起来得到一个标识符。

   示例：

   Prose form                Correct               Incorrect
   ------------------------------------------------------------------
   "XML HTTP request"        XmlHttpRequest        XMLHTTPRequest
   "new customer ID"         newCustomerId         newCustomerID
   "inner stopwatch"         innerStopwatch        innerStopWatch
   "supports IPv6 on iOS?"   supportsIpv6OnIos     supportsIPv6OnIOS
   "YouTube importer"        YouTubeImporter
                             YoutubeImporter*
   

   注意：在英语中，某些带有连字符的单词形式不唯一。例如：”nonempty”和”non-empty”都是正确的，因此方法名checkNonempty和checkNonEmpty也都是正确的。
   
   
   
   

二、正确的换行

  一般情况下，写一行长代码为了避免超出列限制(80或100个字符)而被分为多行的情况，我们称之为自动换行(line-wrapping)。
  自动换行后至少缩进4个空格，第一行后的每一行至少比第一行多缩进4个空格；但注意，制表符是不用于缩进的，正确做法应该是使用ASCII水平空格字符(0x20，即空格) 进行格式缩进。

自动换行的基本准则是：

1. 如果在非赋值运算符处断开，那么在该符号前断开（比如+，它将位于下一行）
2. 如果在赋值运算符处断开，通常的做法是在该符号后断开（比如=，它与前面的内容留在同一行。这条规则也适用于foreach语 句中的分号）
3. 方法名或构造函数名与左括号留在同一行
4. 逗号(,)与前面的内容留在同一行

  当存在连续自动换行时 ，缩进可能会缩进不只4个空格（语法元素存在多级时）。一般而言，两个连续使用相同的缩进当且仅当他们开始于同级语法元素

三、对括号的处理

 1.使用大括号（即使是可选的）

  大括号if else for do…while 语句一起使用，即使只有一条语句（或是空），也应该把大括号写上

 2. 非空块(K & B 风格)

   对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格
   即：

  a)左大括号前不换行
  b)左大括号后换行
  c)右大括号前换行
  d)如果右大括号是一个语句、函数体或类的终止，则右大括号后换行，否则不换行。例如，如果右大括号后面是else或逗号，则不换行

return new MyClass() {
  @Override public void method() {
 if (condition()) {
   try {
     something();
   } catch (ProblemException e) {
     recover();
   	  }
 	}
  }
};

  一个空块结构里什么也不包含，大括号可以简洁地写成{}。
  例如：如果它是一个多块语句的一部分(if/else或try/catch/finally)，即使大括号内没内容，右大括号也要换行

void doNothing(){};

 3.用小括号来限定组（推荐！）

  除非作者和reviewer都认为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于阅读，否则我们不应该去掉小括号。 我们没有理由假设读者能记住整个Java运算符优先级表。

四、Javadoc格式规范

 1.格式

  1. 1一般格式

Javadoc块的基本格式如下所示：

/**
* Multiple lines of Javadoc text are written here,
 * wrapped normally...
*/
public int method(String p1) { ... }

或者是以下单行形式：

/** An especially short bit of Javadoc. */

  基本格式总是OK的。当整个Javadoc块能容纳于一行时(且没有Javadoc标记@XXX)，可以使用单行形式。

  1.2段落

  空行(即，只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。 除了第一个段落，每个段落第一个单词前都有标签<p>，并且它和第一个单词间没有空格。

  1.3Javadoc标记

   标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。 当描述无法在一行中容纳，连续行需要至少再缩进4个空格。

  1.4摘要片段

  每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中。
   这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。它不会以A {@code Foo} is a...或This method returns...开头, 它也不会是一个完整的祈使句，如Save the record...。然而，由于开头大写及被加了标点，它看起来就像是个完整的句子。

Tip：一个常见的错误是把简单的Javadoc写成/** @return the customer ID */，这是不正确的。它应该写成/** Returns the customer ID. */。

 2.哪里需要使用Javadoc

  至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：

   2.1例外：不可言明的方法

     对于简单明显的方法如getFoo，Javadoc是可选的(即，是可以不写的)。这种情况下除了写“Returns the foo”，确实也没有什么值得写了。
     单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。

Tip：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCanonicalName， 就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。

   2.2例外：重载

    如果一个方法重载了超类中的方法，那么Javadoc并非必需的。

   2.3例外：可选的Javadoc

    对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为， 那么这个注释应该写成Javadoc，这样更统一更友好。

五、其他

 1.文件编码

  源文件编码设置为为UTF-8

 2.文件名字

  源文件以其最顶层的类名名来命名，大小写敏感，文件扩展名为.java

 3.源文件结构

  一个源文件包含（按顺序地）：

  a)许可证或版权信息（如有需要）
  b)pack语句
  c)import语句
  d)一个*类（只有一个）

  以上每个部分之间用一个空行隔开

  3.1 许可证或版权信息

     如果一个文件包含许可证或版权信息，那么它应该被放在文件前面

  3.2 package语句

     package语句不换行，列限制并不适用于packge语句。（即package语句写在一行里）

  3.3 import语句

   3.3.1 import不要使用通配符

    不要出现类似这样地import语句：import java.util.*;

   3.3.2 不要换行

    import语句不换行，列限制并不适用于import语句（每个import语句独立成行）

   3.3.3 顺序和间距

    import语句可分为以下几组，按照这个顺序，没组有一个空行分隔

    a)所有的静态导入独立成组
    b)com.google import （仅当这个源文件实在com.google包下）
    c) 第三方地包。每个*包为一个组；字典序。例如：android,com,junit,org,sun
    d)java imports
    e)javax imports

  注意：组内不空行，按字典序排列

 4.类声明

  4.1只有一个*类声明

    每个*类都在一个与它同名的源文件中（当然，还包含.java后缀）
    例外：packge-info.java，该文件中可没有package-info类（此文件不可被随便创建）

  4.2类成员顺序

    类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。最重要的一点，每个类应该以某种逻辑取排序他的成员，维护者应该要能解释这种排序逻辑。
    比如：当引得方法不能总是习惯性的添加到类的结尾，因为这样就是按照时间顺序而非某种逻辑来排列

 重载：当一个类有多个构造函数，或是多个同名方法，这些函数/方法应该按顺序出现在一起，中间不要放进其他函数/方法

---

                                                字   数：5645
                                                用   时：3h
                                                完成时间：2020年04月22日