1.Resource文件

命名

遵循前缀表明类型的习惯，形如type_foo_bar.xml。如：fragment_contact_details.xml，view_primary_button.xml，activity_main.xml。

组织布局文件

遵循以下规则来排版你的布局文件：

• 每一个属性一行，缩进4个空格
• android:id 总是作为第一个属性
• android:layout_**** 属性在上边
• style 属性在底部
• 关闭标签 />单独起一行，有助于调整和添加新的属性
• 考虑使用Designtime attributes 设计时布局属性，Android Studio已经提供支持，而不是硬编码android:text
  (译者注：墙内也可以参考stormzhang的这篇博客链接)

※使用IDE的快捷键帮助代码格式化更为高效，Android Studio：Ctrl+Alt+L， Eclipse：先卸载Eclipse并安装Android Studio然后参考前面

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
     xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:orientation="vertical"
     >
     <TextView
          android:id="@+id/name"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:layout_alignParentRight="true"
          android:text="@string/name"
          style="@style/FancyText"
          />
     <include layout="@layout/reusable_part" />
</LinearLayout>

作为一个经验法则,android:layout_******属性应该在layout中定义,同时其它属性android:******应放在style中。此规则也有例外，不过大体工作 的很好。这个思想整体是保持layout属性(positioning, margin, sizing) 和content属性在布局文件中，同时将所有的外观细节属性（colors, padding, font）放在style文件中。

这里我们需要注意以下情况：

• android:id 明显应该在 layout 文件中
• layout 文件中 android:orientation 对于一个LinearLayout布局通常更有意义
• android:text 由于是定义内容，应该放在 layout 文件中
• 有时候将android:layout_width 和 android:layout_height 属性放到一个style中作为一个通用的风格中更有意义，但是默认情况下这些应该放到layout文件中

合理的使用Style文件

几乎每个项目都需要适当的使用style文件，因为对于同一个应用来说，为了保持风格的统一，重复的外观是很常见的。例如：

<style name="ContentText">
       <item name="android:textSize">@dimen/font_normal</item>
       <item name="android:textColor">@color/basic_black</item>
</style>

应用到TextView 中：

<TextView
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="@string/price"
       style="@style/ContentText"
       />

你也可以为其他控件做同样的事情，而且你可以做得更多。将一组相关的和重复android:****的属性放到一个通用的style中，这样在项目的开发维护阶段都能为你省很多事。

将一个大的style文件分割成多个文件

你可以有多个styles.xml文件。Android SDK支持其它文件，styles这个文件名称并没有作用，起作用的是在文件 里xml的<style>标签。因此你可以有多个style文件。如：styles.xml，style_home.xml，style_item_details.xml,styles_forms.xml。 这样就很好的将style文件模块化。不用于资源文件路径需要为系统构建起的有意义，在res/values目录下的文件可以任意命名。

colors.xml只是一个调色板

在你的colors.xml文件中应该只是映射颜色的名称一个RGBA值，而没有其它的。不要使用它为不同的按钮来定义RGBA值。
错误例子：

<resources>
       <color name="button_foreground">#FFFFFF</color>
       <color name="button_background">#2A91BD</color>
       <color name="comment_background_inactive">#5F5F5F</color>
       <color name="comment_background_active">#939393</color>
       <color name="comment_foreground">#FFFFFF</color>
       <color name="comment_foreground_important">#FF9D2F</color>
</resources>

向应用设计者那里要这个调色板，名称不需要跟"green", "blue", 等等相同。 "brand_primary", "brand_secondary", "brand_negative" 这样的名字也是完全可以接受的。 像这样规范的颜色很容易修改或重构，会使应用一共使用了多少种不同的颜色变得非常清晰。 通常一个具有审美价值的UI来说，减少使用颜色的种类是非常重要的。

像对待colors.xml一样对待dimens.xml文件

与定义颜色调色板一样，你同时也应该定义一个空隙间隔和字体大小的“调色板”。 一个好的例子，如下所示：

<resources>
       <!-- font sizes -->
       <dimen name="font_larger">22sp</dimen>
       <dimen name="font_large">18sp</dimen>
       <dimen name="font_normal">15sp</dimen>
       <dimen name="font_small">12sp</dimen>

       <!-- typical spacing between two views -->
       <dimen name="spacing_huge">40dp</dimen>
       <dimen name="spacing_large">24dp</dimen>
       <dimen name="spacing_normal">14dp</dimen>
       <dimen name="spacing_small">10dp</dimen>
       <dimen name="spacing_tiny">4dp</dimen>

       <!-- typical sizes of views -->
       <dimen name="button_height_tall">60dp</dimen>
       <dimen name="button_height_normal">40dp</dimen>
       <dimen name="button_height_short">32dp</dimen>
</resources>

布局时在写 margins 和 paddings 时，你应该使用spacing_****尺寸格式来布局，而不是像对待String字符串一样直接写值。 这样写会非常有感觉，会使组织和改变风格或布局是非常容易。

避免深层次的视图结构

有时候为了摆放一个视图，你可能尝试添加另一个LinearLayout。你可能使用这种方法解决：

<LinearLayout
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:orientation="vertical" >
       <RelativeLayout ... >
              <LinearLayout ... >
                     <LinearLayout ... >
                            <LinearLayout ... >
                            </LinearLayout>
                     </LinearLayout>
              </LinearLayout>
       </RelativeLayout>
</LinearLayout>

即使你没有非常明确的在一个layout布局文件中这样使用，如果你在Java文件中从一个view inflate（这个inflate翻译不过去，大家理解就行） 到其他views当中，也是可能会发生的。

可能会导致一系列的问题。你可能会遇到性能问题，因为处理起需要处理一个复杂的UI树结构。 还可能会导致以下更严重的问题StackOverflowError.

因此尽量保持你的视图tree：学习如何使用RelativeLayout, 如何 optimize 你的布局 和如何使用 <merge>
标签.

小心关于WebViews的问题

如果你必须显示一个web视图， 比如说对于一个新闻文章，避免做客户端处理HTML的工作， 最好让后端工程师协助，让他返回一个 "纯" HTML。 WebViews 也能导致内存泄露 当保持引他们的Activity，而不是被绑定到ApplicationContext中的时候。 当使用简单的文字或按钮时，避免使用WebView，这时使用TextView或Buttons更好。

2.Java文件

文件名

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

编码格式

源文件编码格式为UTF-8。

特殊字符

1.空白字符

除了行结束符序列，ASCII水平空格字符(0x20，即空格)是源文件中唯一允许出现的空白字符，这意味着：

• 所有其它字符串中的空白字符都要进行转义。
• 制表符不用于缩进。

2.特殊转义序列

对于具有特殊转义序列的任何字符(\b, \t, \n, \f, \r, ", '及)，我们使用它的转义序列，而不是相应的八进制(比如\012)或Unicode(比如\u000a)转义。

3.非ASCII字符

对于剩余的非ASCII字符，是使用实际的Unicode字符(比如∞)，还是使用等价的Unicode转义符(比如\u221e)，取决于哪个能让代码更易于阅读和理解。
Tip: 在使用Unicode转义符或是一些实际的Unicode字符时，建议做些注释给出解释，这有助于别人阅读和理解。
例如：

       String unitAbbrev = "μs";                              | 赞，即使没有注释也非常清晰
       String unitAbbrev = "\u03bcs"; // "μs"                 | 允许，但没有理由要这样做
       String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" | 允许，但这样做显得笨拙还容易出错
       String unitAbbrev = "\u03bcs";                         | 很糟，读者根本看不出这是什么
       return '\ufeff' + content; // byte order mark          | Good，对于非打印字符，使用转义，并在必要时写上注释

Tip: 永远不要由于害怕某些程序可能无法正确处理非ASCII字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时，它自然无法正确运行， 你就会去fix这些问题的了。(言下之意就是大胆去用非ASCII字符，如果真的有需要的话)

源文件结构

1.许可证或版权信息

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

2.package语句

package语句不换行，列限制(4.4节)并不适用于package语句。(即package语句写在一行里)

3.import语句

• import不要使用通配符 即不要出现类似这样的import语句：import java.util.*；
• 不要换行 import语句不换行，列限制(4.4节)并不适用于import语句。(每个import语句独立成行)；
• 顺序和间距 import语句可分为以下几组，按照这个顺序，每组由一个空行分隔：
  ①所有的静态导入独立成组
  ②com.google imports(仅当这个源文件是在com.google包下)
  ③第三方的包。每个顶级包为一组，字典序。例如：android, com, junit, org, sun
  ④java imports
  ⑤javax imports
  组内不空行，按字典序排列。

4.类声明

• 只有一个顶级类声明 每个顶级类都在一个与它同名的源文件中(当然，还包含.java后缀)。
  例外：package-info.java，该文件中可没有package-info类。
• 类成员顺序
  类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。 最重要的一点，每个类应该以某种逻辑去排序它的成员，维护者应该要能解释这种排序逻辑。比如， 新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。
• 重载：永不分离
  当一个类有多个构造函数，或是多个同名方法，这些函数/方法应该按顺序出现在一起，中间不要放进其它函数/方法。

5.大括号

• 使用大括号(即使是可选的) 大括号与if, else, for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。
• 非空块：K & R 风格 对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格 (Egyptian brackets):
  ①左大括号前不换行
  ②左大括号后换行
  ③右大括号前换行
  ④如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。例如，如果右大括号后面是else或逗号，则不换行
  示例：

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

enum类有一些例外

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

void doNothing() {}

6.块缩进：2个空格

每当开始一个新的块，缩进增加2个空格，当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。

7.一行一个语句

每个语句后要换行。

8.列限制：80或100

一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。
例外：

• 不可能满足列限制的行(例如，Javadoc中的一个长URL，或是一个长的JSNI方法参考)
• package和import语句
• 注释中那些可能被剪切并粘贴到shell中的命令行

9.自动换行

一般情况下，一行长代码为了避免超出列限制(80或100个字符)而被分为多行，我们称之为自动换行(line-wrapping)。
我们并没有全面，确定性的准则来决定在每一种情况下如何自动换行。很多时候，对于同一段代码会有好几种有效的自动换行方式。
Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题(是合理缩短命名长度吧)

• 从哪里断开 自动换行的基本准则是：更倾向于在更高的语法级别处断开。
  ①如果在非赋值运算符处断开，那么在该符号前断开(比如+，它将位于下一行)。注意：这一点与Google其它语言的编程风格不同(如C++和JavaScript)。 这条规则也适用于以下“类运算符”符号：点分隔符(.)，类型界限中的&（<T extends Foo & Bar>)，catch块中的管道符号(catch (FooException | BarException e)
  ②如果在赋值运算符处断开，通常的做法是在该符号后断开(比如=，它与前面的内容留在同一行)。这条规则也适用于foreach语句中的分号
  ③方法名或构造函数名与左括号留在同一行
  ④逗号(,)与其前面的内容留在同一行
• 自动换行时缩进至少+4个空格 自动换行时，第一行后的每一行至少比第一行多缩进4个空格(注意：制表符不用于缩进)。当存在连续自动换行时，缩进可能会多缩进不只4个空格(语法元素存在多级时)。一般而言，两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。

10.空白

• 垂直空白 以下情况需要使用一个空行：
  ①类内连续的成员之间：字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块
  例外：两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组。
  ②在函数体内，语句的逻辑分组间使用空行
  ③类内的第一个成员前或最后一个成员后的空行是可选的(既不鼓励也不反对这样做，视个人喜好而定)
  ④要满足本文档中其他节的空行要求(比如：前面讲的import语句)
  多个连续的空行是允许的，但没有必要这样做(我们也不鼓励这样做)。
• 水平空白 除了语言需求和其它规则，并且除了文字，注释和Javadoc用到单个空格，单个ASCII空格也出现在以下几个地方：
  ①分隔任何保留字与紧随其后的左括号(()(如if, for catch等)
  ②分隔任何保留字与其前面的右大括号(})(如else, catch)
  ③在任何左大括号前({)
  两个例外：@SomeAnnotation({a, b})(不使用空格)；String[][] x = foo；(大括号间没有空格，见下面的Note)
  ④在任何二元或三元运算符的两侧。这也适用于以下“类运算符”符号
  类型界限中的&(<T extends Foo & Bar>)
  catch块中的管道符号(catch (FooException | BarException e)
  foreach语句中的分号
  ⑤在, : ;及右括号())后
  ⑥如果在一条语句后做注释，则双斜杠(//)两边都要空格。这里可以允许多个空格，但没有必要
  ⑦类型和变量之间：List list
  ⑧数组初始化中，大括号内的空格是可选的，即new int[] {5, 6}和new int[] { 5, 6 }都是可以的
  Tip：这个规则并不要求或禁止一行的开关或结尾需要额外的空格，只对内部空格做要求。
• 水平对齐：不做要求 水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。这是允许的(而且在不少地方可以看到这样的代码)，但Google编程风格对此不做要求。即使对于已经使用水平对齐的代码，我们也不需要去保持这种风格。
  示例：

       //未对齐
       private int x; // this is fine
       private Color color; // this too
       
       //对齐
       private int x; // permitted, but future edits
       private Color color; // may leave it unaligned

Tip：对齐可增加代码可读性，但它为日后的维护带来问题。考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。 这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格)， 这就会让你做许多的无用功，增加了reviewer的工作并且可能导致更多的合并冲突。(我们选择不对齐)

11.用小括号来限定组：推荐

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

12.具体结构

• 枚举类 枚举常量间用逗号隔开，换行可选。没有方法和文档的枚举类可写成数组初始化的格式：private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }由于枚举类也是一个类，因此所有适用于其它类的格式规则也适用于枚举类。
• 变量声明
  ①每次只声明一个变量 不要使用组合声明，比如int a, b;。
  ②需要时才声明，并尽快进行初始化 不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。
  ③在任何左大括号前({)
• 数组
  ①数组初始化：可写成块状结构 数组初始化可以写成块状结构，比如，下面的写法都是OK的（推荐使用第四种）：

//第一种
new int[] {
       0, 1, 2, 3
}
//第二种
new int[] {
       0,
       1,
       2,
       3
}
//第三种
new int[] {
       0, 1,
       2, 3
}
//第四种
new int[]{0, 1, 2, 3}

**②非C风格的数组声明** 中括号是类型的一部分：String[] args， 而非String args[]。

• switch语句 switch块的大括号内是一个或多个语句组。每个语句组包含一个或多个switch标签(case FOO:或default:)，后面跟着一条或多条语句。
  ①缩进 与其它块状结构一致，switch块中的内容缩进为2个空格。每个switch标签后新起一行，再缩进2个空格，写下一条或多条语句。
  ②Fall-through：注释 在一个switch块内，每个语句组要么通过break, continue, return
  或抛出异常来终止，要么通过一条注释来说明程序将继续执行到下一个语句组， 任何能表达这个意思的注释都是OK的(典型的是用// fall through)。这个特殊的注释并不需要在最后一个语句组(一般是default)中出现。示例：

switch (input) {
       case 1:
       case 2:
              prepareOneOrTwo(); // fall through 
       case 3: handleOneTwoOrThree();
              break;
       default:
              handleLargeNumber(input);}

**③default的情况要写出来** 

每个switch语句都包含一个default语句组，即使它什么代码也不包含。

• 注解(Annotations) 注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。这些换行不属于自动换行(第4.5节，自动换行)，因此缩进级别不变。例如：

@Override
@Nullablepublic
String getNameIfPresent() { ... }

例外：单个的注解可以和签名的第一行出现在同一行，如：@Override public int hashCode() { ... }；应用于字段的注解紧随文档块出现，应用于字段的多个注解允许与字段出现在同一行，如：@Partial @Mock DataLoader loader。
参数和局部变量注解没有特定规则。

• 注释
  ①块注释风格 块注释与其周围的代码在同一缩进级别。它们可以是/* ... /风格，也可以是// ...风格。对于多行的/ ... /注释，后续行必须从开始， 并且与前一行的*对齐。以下示例注释都是OK的。

/*
   * This is 
   * okay. 
   */
// And so
// is this.
/* Or you can
   * even do this. */

• Modifiers 类和成员的modifiers如果存在，则按Java语言规范中推荐的顺序出现。
  public protected private abstract static final transient volatile synchronized native strictfp

命名约定

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

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

2.标识符类型的规则

• 包名 全部小写，连续的单词只是简单地连接起来，不使用下划线。**
• 类名 类名都以UpperCamelCase。类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。测试类的命名以它要测试的类的名称开始，以Test结束。例如，HashTest或HashIntegrationTest。风格编写。
• 方法名 方法名都以lowerCamelCase风格编写。方法名通常是动词或动词短语。下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是：test<MethodUnderTest>_<state>，例testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法。
• 常量名 常量名命名模式为CONSTANT_CASE，全部字母大写，用下划线分隔单词。

// Constant
sstatic 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"};

这些名字通常是名词或名词短语。

• 非常量字段名 非常量字段名以lowerCamelCase风格编写。这些名字通常是名词或名词短语。
• 参数名 参数名以lowerCamelCase风格编写。参数应该避免用单个字符命名。
• 局部变量名 局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。
• 类型变量名 类型变量可用以下两种风格之一进行命名：
  ①单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)
  ②以类命名方式(5.2.2节)，后面加个大写的T(如：RequestT, FooBarT)

3.驼峰式命名法(CamelCase)

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

• 把短语转换为纯ASCII码，并且移除任何单引号。例如：”Müller’s algorithm”将变成”Muellers algorithm”
• 把这个结果切分成单词，在空格或其它标点符号(通常是连字符)处分割开。
  推荐：如果某个单词已经有了常用的驼峰表示形式，按它的组成将它分割开(如”AdWords”将分割成”ad words”)。 需要注意的是”iOS”并不是一个真正的驼峰表示形式，因此该推荐对它并不适用。
• 现在将所有字母都小写(包括缩写)，然后将单词的第一个字母大写：
  每个单词的第一个字母都大写，来得到大驼峰式命名。
  除了第一个单词，每个单词的第一个字母都大写，来得到小驼峰式命名。
• 最后将所有的单词连接起来得到一个标识符。
  Note：在英语中，某些带有连字符的单词形式不唯一。例如：”nonempty”和”non-empty”都是正确的，因此方法名checkNonempty和checkNonEmpty也都是正确的。

编程实践

1.@Override：能用则用

只要是合法的，就把@Override注解给用上。

2.捕获的异常：不能忽视

除了下面的例子，对捕获的异常不做响应是极少正确的。(典型的响应方式是打印日志，或者如果它被认为是不可能的，则把它当作一个AssertionError重新抛出。)
如果它确实是不需要在catch块中做任何响应，需要做注释加以说明(如下面的例子)。

try {
       int i = Integer.parseInt(response);
       return handleNumericResponse(i);
} catch (NumberFormatException ok) {
       // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

在测试中，如果一个捕获的异常被命名为expected，则它可以被不加注释地忽略。下面是一种非常常见的情形，用以确保所测试的方法会抛出一个期望中的异常， 因此在这里就没有必要加注释。

try {
       emptyStack.pop();
       fail();
} catch (NoSuchElementException expected) {
}

3.静态成员：使用类进行调用

使用类名调用静态的类成员，而不是具体某个对象或表达式。

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

4.Finalizers: 禁用

极少会去重写Object.finalize
Tip：不要使用finalize。如果你非要使用它，请先仔细阅读和理解Effective Java 第7条款：“Avoid Finalizers”，然后不要使用它。

Javadoc

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)，可以使用单行形式。

• 段落 空行(即，只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。 除了第一个段落，每个段落第一个单词前都有标签<\p>，并且它和第一个单词间没有空格。
• Javadoc标记 标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。 当描述无法在一行中容纳，连续行需要至少再缩进4个空格。

2.摘要片段

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

3.哪里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：
①例外：不言自明的方法 对于简单明显的方法如getFoo，Javadoc是可选的(即，是可以不写的)。这种情况下除了写“Returns the foo”，确实也没有什么值得写了。单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。
Tip：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCanonicalName， 就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。
②例外：重写 如果一个方法重写了超类中的方法，那么Javadoc并非必需的。
③可选的Javadoc 对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为， 那么这个注释应该写成Javadoc，这样更统一更友好。