Google编程标准规范专业资料.doc

Google Java编程风格指南 January 20， 作者：Hawstein出处：声明：本文采用如下合同进行授权： 自由转载-非商用-非衍生-保持签名|Creative Commons BY-NC-ND 3.0 ，转载请注明作者及出处。目录1. 前言2. 源文献基本3. 源文献构造4. 格式5. 命名商定6. 编程实践7. Javadoc8. 后记前言这份文档是Google Java编程风格规范完整定义。当且仅当一种Java源文献符合此文档中规则， 咱们才以为它符合GoogleJava编程风格。与其他编程风格指南同样，这里所讨论不但仅是编码格式美不美观问题， 同步也讨论某些商定及编码原则。然而，这份文档重要侧重于咱们所普遍遵循规则， 对于那些不是明确强制规定，咱们尽量避免提供意见。1.1 术语阐明在本文档中，除非另有阐明：1. 术语class可表达一种普通类，枚举类，接口或是annotation类型(interface)2. 术语comment只用来指代实现注释(implementation comments)，咱们不使用“documentation comments”一词，而是用Javadoc。其她术语阐明会偶尔在背面文档浮现。1.2 指南阐明本文档中示例代码并不作为规范。也就是说，虽然示例代码是遵循Google编程风格，但并不意味着这是呈现这些代码唯一方式。 示例中格式选取不应当被强制定为规则。源文献基本2.1 文献名源文献以其最顶层类名来命名，大小写敏感，文献扩展名为.java。2.2 文献编码：UTF-8源文献编码格式为UTF-8。2.3 特殊字符2.3.1 空白字符除了行结束符序列，ASCII水平空格字符(0x20，即空格)是源文献中唯一容许浮现空白字符，这意味着：1. 所有其他字符串中空白字符都要进行转义。2. 制表符不用于缩进。2.3.2 特殊转义序列对于具备特殊转义序列任何字符(b，t，n，f，r，“，及)，咱们使用它转义序列，而不是相应八进制(例如012)或Unicode(例如u000a)转义。2.3.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语句3. import语句4. 一种顶级类(只有一种)以上每个某些之间用一种空行隔开。3.1 允许证或版权信息如果一种文献包括允许证或版权信息，那么它应当被放在文献最前面。3.2 package语句package语句不换行，列限制(4.4节)并不合用于package语句。(即package语句写在一行里)3.3 import语句3.3.1 import不要使用通配符即，不要浮现类似这样import语句：import java.util.*;3.3.2 不要换行import语句不换行，列限制(4.4节)并不合用于import语句。(每个import语句独立成行)3.3.3 顺序和间距import语句可分为如下几组，按照这个顺序，每组由一种空行分隔：1. 所有静态导入独立成组2. com.google imports(仅当这个源文献是在com.google包下)3. 第三方包。每个顶级包为一组，字典序。例如：android，com，junit，org，sun4. java imports5. javax imports组内不空行，按字典序排列。3.4 类声明3.4.1 只有一种顶级类声明每个顶级类都在一种与它同名源文献中(固然，还包括.java后缀)。例外：package-info.java，该文献中可没有package-info类。3.4.2 类成员顺序类成员顺序对易学性有很大影响，但这也不存在唯一通用法则。不同类对成员排序也许是不同。 最重要一点，每个类应当以某种逻辑去排序它成员，维护者应当要能解释这种排序逻辑。例如， 新办法不能总是习惯性地添加到类结尾，由于这样就是准时间顺序而非某种逻辑来排序。3.4.2.1 重载：永不分离当一种类有各种构造函数，或是各种同名办法，这些函数/办法应当按顺序出当前一起，中间不要放进其他函数/办法。格式术语阐明：块状构造(block-like construct)指是一种类，办法或构造函数主体。需要注意是，数组初始化中初始值可被选取性地视为块状构造(4.8.3.1节)。4.1 大括号4.1.1 使用大括号(虽然是可选)大括号与if，else，for，do，while语句一起使用，虽然只有一条语句(或是空)，也应当把大括号写上。4.1.2 非空块：K & R 风格对于非空块和块状构造，大括号遵循Kernighan和Ritchie风格 (Egyptian brackets): 左大括号前不换行 左大括号后换行 右大括号前换行 如果右大括号是一种语句、函数体或类终结，则右大括号后换行；否则不换行。例如，如果右大括号背面是else或逗号，则不换行。示例：return new MyClass() Override public void method() if (condition() try something(); catch (ProblemException e) recover(); ;4.8.1节给出了enum类某些例外。4.1.3 空块：可以用简洁版本一种空块状构造里什么也不包括，大括号可以简洁地写成，不需要换行。例外：如果它是一种多块语句一某些(if/else 或 try/catch/finally) ，虽然大括号内没内容，右大括号也要换行。示例：void doNothing() 4.2 块缩进：2个空格每当开始一种新块，缩进增长2个空格，当块结束时，缩进返回先前缩进级别。缩进级别合用于代码和注释。(见4.1.2节中代码示例)4.3 一行一种语句每个语句后要换行。4.4 列限制：80或100一种项目可以选取一行80个字符或100个字符列限制，除了下述例外，任何一行如果超过这个字符数限制，必要自动换行。例外：1. 不也许满足列限制行(例如，Javadoc中一种长URL，或是一种长JSNI办法参照)。2. package和import语句(见3.2节和3.3节)。3. 注释中那些也许被剪切并粘贴到shell中命令行。4.5 自动换行术语阐明：普通状况下，一行长代码为了避免超过列限制(80或100个字符)而被分为多行，咱们称之为自动换行(line-wrapping)。咱们并没有全面，拟定性准则来决定在每一种状况下如何自动换行。诸多时候，对于同一段代码会有好几种有效自动换行方式。Tip：提取办法或局部变量可以在不换行状况下解决代码过长问题(是合理缩短命名长度吧)4.5.1 从哪里断开自动换行基本准则是：更倾向于在更高语法级别处断开。1. 如果在非赋值运算符处断开，那么在该符号前断开(例如+，它将位于下一行)。注意：这一点与Google其他语言编程风格不同(如C+和JavaScript)。 这条规则也合用于如下“类运算符”符号：点分隔符(.)，类型界限中&（)，catch块中管道符号(catch (FooException | BarException e)2. 如果在赋值运算符处断开，普通做法是在该符号后断开(例如=，它与前面内容留在同一行)。这条规则也合用于foreach语句中分号。3. 办法名或构造函数名与左括号留在同一行。4. 逗号(,)与其前面内容留在同一行。4.5.2 自动换行时缩进至少+4个空格自动换行时，第一行后每一行至少比第一行多缩进4个空格(注意：制表符不用于缩进。见2.3.1节)。当存在持续自动换行时，缩进也许会多缩进不只4个空格(语法元素存在多级时)。普通而言，两个持续行使用相似缩进当且仅当它们开始于同级语法元素。第4.6.3水平对齐一节中指出，不勉励使用可变数目空格来对齐前面行符号。4.6 空白4.6.1 垂直空白如下状况需要使用一种空行：1. 类内持续成员之间：字段，构造函数，办法，嵌套类，静态初始化块，实例初始化块。 o 例外：两个持续字段之间空行是可选，用于字段空行重要用来对字段进行逻辑分组。2. 在函数体内，语句逻辑分组间使用空行。3. 类内第一种成员前或最后一种成员后空行是可选(既不勉励也不反对这样做，视个人喜好而定)。4. 要满足本文档中其她节空行规定(例如3.3节：import语句)各种持续空行是容许，但没有必要这样做(咱们也不勉励这样做)。4.6.2 水平空白除了语言需求和其他规则，并且除了文字，注释和Javadoc用到单个空格，单个ASCII空格也出当前如下几种地方：1. 分隔任何保存字与紧随其后左括号()(如if，for catch等)。2. 分隔任何保存字与其前面右大括号()(如else，catch)。3. 在任何左大括号前()，两个例外： o SomeAnnotation(a，b)(不使用空格)。o String x = foo;(大括号间没有空格，见下面Note)。4. 在任何二元或三元运算符两侧。这也合用于如下“类运算符”符号： o 类型界限中&()。o catch块中管道符号(catch (FooException | BarException e)。o foreach语句中分号。5. 在，：;及右括号()后6. 如果在一条语句后做注释，则双斜杠(/)两边都要空格。这里可以容许各种空格，但没有必要。7. 类型和变量之间：List list。8. 数组初始化中，大括号内空格是可选，即new int 5，6和new int 5，6 都是可以。Note：这个规则并不规定或禁止一行开关或结尾需要额外空格，只对内部空格做规定。4.6.3 水平对齐：不做规定术语阐明：水平对齐指是通过增长可变数量空格来使某一行字符与上一行相应字符对齐。这是容许(并且在不少地方可以看到这样代码)，但Google编程风格对此不做规定。虽然对于已经使用水平对齐代码，咱们也不需要去保持这种风格。如下示例先展示未对齐代码，然后是对齐代码：private int x；/ this is fineprivate Color color；/ this tooprivate int x； / permitted，but future editsprivate Color color； / may leave it unalignedTip：对齐可增长代码可读性，但它为日后维护带来问题。考虑将来某个时候，咱们需要修改一堆对齐代码中一行。 这也许导致原本很美丽对齐代码变得错位。很也许它会提示你调节周边代码空白来使这一堆代码重新水平对齐(例如程序员想保持这种水平对齐风格)， 这就会让你做许多无用功，增长了reviewer工作并且也许导致更多合并冲突。4.7 用小括号来限定组：推荐除非作者和reviewer都以为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于阅读，否则咱们不应当去掉小括号。 咱们没有理由假设读者能记住整个Java运算符优先级表。4.8 详细构造4.8.1 枚举类枚举常量间用逗号隔开，换行可选。没有办法和文档枚举类可写成数组初始化格式：private enum Suit CLUBS，HEARTS，SPADES，DIAMONDS 由于枚举类也是一种类，因而所有合用于其他类格式规则也合用于枚举类。4.8.2 变量声明4.8.2.1 每次只声明一种变量不要使用组合声明，例如int a，b;。4.8.2.2 需要时才声明，并尽快进行初始化不要在一种代码块开头把局部变量一次性都声明了(这是c语言做法)，而是在第一次需要使用它时才声明。 局部变量在声明时最佳就进行初始化，或者声明后尽快进行初始化。4.8.3 数组4.8.3.1 数组初始化：可写成块状构造数组初始化可以写成块状构造，例如，下面写法都是OK：new int 0，1，2，3 new int 0, 1, 2, 3new int 0，1, 2，3new int 0，1，2，34.8.3.2 非C风格数组声明中括号是类型一某些：String args， 而非String args。4.8.4 switch语句术语阐明：switch块大括号内是一种或各种语句组。每个语句组包括一种或各种switch标签(case FOO:或default:)，背面跟着一条或多条语句。4.8.4.1 缩进与其他块状构造一致，switch块中内容缩进为2个空格。每个switch标签后新起一行，再缩进2个空格，写下一条或多条语句。4.8.4.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);4.8.4.3 default状况要写出来每个switch语句都包括一种default语句组，虽然它什么代码也不包括。4.8.5 注解(Annotations)注解紧跟在文档块背面，应用于类、办法和构造函数，一种注解独占一行。这些换行不属于自动换行(第4.5节，自动换行)，因而缩进级别不变。例如：OverrideNullablepublic String getNameIfPresent() . 例外：单个注解可以和签名第一行出当前同一行。例如：Override public int hashCode() . 应用于字段注解紧随文档块浮现，应用于字段各种注解容许与字段出当前同一行。例如：Partial Mock DataLoader loader;参数和局部变量注解没有特定规则。4.8.6 注释4.8.6.1 块注释风格块注释与其周边代码在同一缩进级别。它们可以是/* . */风格，也可以是/ .风格。对于多行/* . */注释，后续行必要从*开始， 并且与前一行*对齐。如下示例注释都是OK。/* * This is / And so /* Or you can * okay. / is this. * even do this. */ */注释不要封闭在由星号或其他字符绘制框架里。Tip：在写多行注释时，如果你但愿在必要时能重新换行(即注释像段落风格同样)，那么使用/* . */。4.8.7 Modifiers类和成员modifiers如果存在，则按Java语言规范中推荐顺序浮现。public protected private abstract static final transient volatile synchronized native strictfp命名商定5.1 对所有标记符都通用规则标记符只能使用ASCII字母和数字，因而每个有效标记符名称都能匹配正则表达式w+。在Google其他编程语言风格中使用特殊前缀或后缀，如name_，mName，s_name和kName，在Java编程风格中都不再使用。5.2 标记符类型规则5.2.1 包名包名所有小写，持续单词只是简朴地连接起来，不使用下划线。5.2.2 类名类名都以UpperCamelCase风格编写。类名普通是名词或名词短语，接口名称有时也许是形容词或形容词短语。当前还没有特定规则或行之有效商定来命名注解类型。测试类命名以它要测试类名称开始，以Test结束。例如，HashTest或HashIntegrationTest。5.2.3 办法名办法名都以lowerCamelCase风格编写。办法名普通是动词或动词短语。下划线也许出当前JUnit测试办法名称中用以分隔名称逻辑组件。一种典型模式是：test_，例如testPop_emptyStack。 并不存在唯一对的方式来命名测试办法。5.2.4 常量名常量名命名模式为CONSTANT_CASE，所有字母大写，用下划线分隔单词。那，究竟什么算是一种常量？每个常量都是一种静态final字段，但不是所有静态final字段都是常量。在决定一种字段与否是一种常量时， 考虑它与否真感觉像是一种常量。例如，如果任何一种该实例观测状态是可变，则它几乎必定不会是一种常量。 只是永远不打算变化对象普通是不够，它要真始终不变才干将它示为常量。/ Constantsstatic final int NUMBER = 5;static final ImmutableList NAMES = ImmutableList.of(Ed，Ann);static final Joiner COMMA_JOINER = Joiner.on(,)； / because Joiner is immutablestatic final SomeMutableType EMPTY_ARRAY = ;enum SomeEnum ENUM_CONSTANT / Not constantsstatic String nonFinal = non-final;final String nonStatic = non-static;static final Set mutableCollection = new HashSet();static final ImmutableSet mutableElements = ImmutableSet.of(mutable);static final Logger logger = Logger.getLogger(MyClass.getName();static final String nonEmptyArray = these，can，change;这些名字普通是名词或名词短语。5.2.5 非常量字段名非常量字段名以lowerCamelCase风格编写。这些名字普通是名词或名词短语。5.2.6 参数名参数名以lowerCamelCase风格编写。参数应当避免用单个字符命名。5.2.7 局部变量名局部变量名以lowerCamelCase风格编写，比起其他类型名称，局部变量名可以有更为宽松缩写。虽然缩写更宽松，但还是要避免用单字符进行命名，除了暂时变量和循环变量。虽然局部变量是final和不可变化，也不应当把它示为常量，自然也不能用常量规则去命名它。5.2.8 类型变量名类型变量可用如下两种风格之一进行命名： 单个大写字母，背面可以跟一种数字(如：E，T，X，T2)。 以类命名方式(5.2.2节)，背面加个大写T(如：RequestT，FooBarT)。5.3 驼峰式命名法(CamelCase)驼峰式命名法分大驼峰式命名法(UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。 有时，咱们有不只一种合理方式将一种英语词组转换成驼峰形式，如缩略语或不寻常构造(例如IPv6或iOS)。Google指定了如下转换方案。名字从散文形式(prose form)开始:1. 把短语转换为纯ASCII码，并且移除任何单引号。例如：Mllers algorithm将变成Muellers algorithm。2. 把这个成果切提成单词，在空格或其他标点符号(普通是连字符)处分割开。 o 推荐：如果某个单词已有了惯用驼峰表达形式，按它构成将它分割开(如AdWords将分割成ad words)。 需要注意是iOS并不是一种真正驼峰表达形式，因而该推荐对它并不合用。3. 当前将所有字母都小写(涉及缩写)，然后将单词第一种字母大写： o 每个单词第一种字母都大写，来得到大驼峰式命名。o 除了第一种单词，每个单词第一种字母都大写，来得到小驼峰式命名。4. 最后将所有单词连接起来得到一种标记符。示例：Prose form Correct Incorrect-XML HTTP request XmlHttpRequest XMLHTTPRequestnew customer ID newCustomerId newCustomerIDinner stopwatch innerStopwatch innerStopWatchsupports IPv6 on iOS? supportsIpv6OnIos supportsIPv6OnIOSYouTube importer YouTubeImporter YoutubeImporter*加星号处表达可以，但不推荐。Note：在英语中，某些带有连字符单词形式不唯一。例如：nonempty和non-empty都是对的，因而办法名checkNonempty和checkNonEmpty也都是对的。编程实践6.1 Override：能用则用只要是合法，就把Override注解给用上。6.2 捕获异常：不能忽视除了下面例子，对捕获异常不做响应是很少对的。(典型响应方式是打印日记，或者如果它被以为是不也许，则把它当作一种AssertionError重新抛出。)如果它的确是不需要在catch块中做任何响应，需要做注释加以阐明(如下面例子)。try int i = Integer.parseInt(response); return handleNumericResponse(i); catch (NumberFormatException ok) / its not numeric；thats fine，just continuereturn handleTextResponse(response);例外：在测试中，如果一种捕获异常被命名为expected，则它可以被不加注释地忽视。下面是一种非经常用情形，用以保证所测试办法会抛出一种盼望中异常， 因而在这里就没有必要加注释。try emptyStack.pop(); fail(); catch (NoSuchElementException expected) 6.3 静态成员：使用类进行调用使用类名调用静态类成员，而不是详细某个对象或表达式。Foo aFoo = .;Foo.aStaticMethod()；/ goodaFoo.aStaticMethod()；/ badsomethingThatYieldsAFoo().aStaticMethod()；/ very bad6.4 Finalizers：禁用很少会去重写Object.finalize。Tip：不要使用finalize。如果你非要使用它，请先仔细阅读和理解Effective Java 第7条款：“Avoid Finalizers”，然后不要使用它。Javadoc7.1 格式7.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)，可以使用单行形式。7.1.2 段落空行(即，只包括最左侧星号行)会出当前段落之间和Javadoc标记(XXX)之前(如果有话)。 除了第一种段落，每个段落第一种单词前均有标签，并且它和第一种单词间没有空格。7.1.3 Javadoc标记原则Javadoc标记按如下顺序浮现：param，return，throws，deprecated，前面这4种标记如果浮现，描述都不能为空。 当描述无法在一行中容纳，持续行需要至少再缩进4个空格。7.2 摘要片段每个类或成员Javadoc以一种简短摘要片段开始。这个片段是非常重要，在某些状况下，它是唯一浮现文本，例如在类和办法索引中。这只是一种小片段，可以是一种名词短语或动词短语，但不是一种完整句子。它不会以A code Foo is a.或This method returns.开头，它也不会是一种完整祈使句，如Save the record.。然而，由于开头大写及被加了标点，它看起来就像是个完整句子。Tip：一种常用错误是把简朴Javadoc写成/* return the customer ID */，这是不对的。它应当写成/* Returns the customer ID. */。7.3 哪里需要使用Javadoc至少在每个public类及它每个public和protected成员处使用Javadoc，如下是某些例外：7.3.1 例外：不言自明办法对于简朴明显办法如getFoo，Javadoc是可选(即，是可以不写)。这种状况下除了写“Returns the foo”，的确也没有什么值得写了。单元测试类中测试办法也许是不言自明最常用例子了，咱们普通可以从这些办法描述性命名中懂得它是干什么，因而不需要额外文档阐明。Tip：如果有某些有关信息是需要读者理解，那么以上例外不应作为忽视这些信息理由。例如，对于办法名getCanonicalName， 就不应当忽视文档阐明，由于读者很也许不懂得词语canonical name指是什么。7.3.2 例外：重写如果一种办法重写了超类中办法，那么Javadoc并非必须。7.3.3 可选Javadoc对于包外不可见类和办法，如有需要，也是要使用Javadoc。如果一种注释是用来定义一种类，办法，字段整体目或行为， 那么这个注释应当写成Javadoc，这样更统一更和谐。