规范
| 版本号 | 修改人 | 修改时间 | 修改内容 |
|---|---|---|---|
| 1.0.0 | 2015-4-1 | 初始化文档 |
目录
背景
随着项目需求不断的增加，代码量越来越大；由于每个人的代码风格不同，或者一些不良编程习惯。导致后面维护人员极难看懂代码。甚至代码不能适应需求，需要重写。为统一代码，养成良好的编码习惯，则需要一套规范以约束开发，养成良好的编程习惯。
目的
提高可读性
编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码
如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误。
理解： 每个人都能够编写出机器所能识别的代码。但是唯有能够编写出人易识别的代码才是优秀的程序员。
代码统一规范，可以提高review效率。可维护性
一个软件的生命周期中，80%的花费在于维护，
几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。
无规范的编写输入输出，或者异常处理，日志处理等等，很容易导致我们出现一些低级的错误或者bug。
理解：风格的相似性，能让开发人员更迅速，更容易理解一些陌生的代码，更快速地理解别人的代码，能更快的进行工作交接。统一全局，促进团队协作
为来自不同的项目组或个人提供标准的代码格式。
成员与成员之间能够更轻松的阅读对方的代码，可以更加关注自身的业务逻辑。提高程序员的个人能力
不可否认，每个程序员都应该养成良好的编码习惯，而编码规范无疑是教材之一。从一个程序员的代码本身能看出很多东西。所以，即便是为了自身发展，作为程序员也没有理由抵制这种规则的存在。你可能没有认识到，我们正默默地得益于编码规范。
如何执行
为了执行规范，每个软件开发人员必须一致遵守编码规范。
参考
规范描述
统一的环境及配置
- 工作空间，源文件编码等，以及服务器配置等统一采用utf-8编码。
- jdk版本采用一致的版本，并且和生产服务器一致。
源文件结构
- 许可证或版权信息（如有需要）
/**
- Copyright: Copyright (c) 湖南快乐阳光互联网传媒有限公司
- @author Comsys-hrg
*/
- package语句
package语句不换行。 import语句
import不要使用通配符。
import语句不换行。
import语句顺序和间距- java imports
- javax imports
- 第三方类库
- 你的应用程序类
- 静态导入组
组内不空行，按字典顺序排列。
一个顶级类(只有一个)
类声明
- 只有一个顶级类声明
- 类成员顺序
- 重载
当一个类有多个构造函数时，或是多个同名方法时，这些函数/方法应该按顺序出现在一起，中间不要出现其他函数/方法。
格式
使用大括号（即使是可选的）
大括号与if,else,for,do,while,语句一起使用，即使只有一条语句（或是空），也应该非空块 风格
把大括号写上。
1.左大括号前不换行。- 做大括号后换行。
- 右大括号前换行。
- 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行，否则不换行。如果右大号后面是else或逗号，不换行。
示例
return new MyClass() {
@Override public void method() {
if (condition()) {
try {
something();
} catch (ProblemException e) {
recover();
}
}
}
};
- 空块 可以使用简洁版本
一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。例外：如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ，即使大括号内没内容，右大括号也要换行。
示例
void doNothing() {}
块缩进： 2个空格
每当开始一个新的块，缩进增加2个空格，当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。一行一个语句
每个语句后要换行。列限制： 80或100
一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。
例外：
1.不可能满足列限制的行(例如，Javadoc中的一个长URL，或是一个长的JSNI方法参考)。
2.package和import语句(见3.2节和3.3节)。
3.注释中那些可能被剪切并粘贴到shell中的命令行。
- 自动换行
我们并没有全面，确定性的准则来决定在每一种情况下如何自动换行。很多时候，对于同一段代码会有好几种有效的自动换行方式。
Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题(是合理缩短命名长度吧)
4.5.1 从哪里断开
自动换行的基本准则是：更倾向于在更高的语法级别处断开。
1.如果在非赋值运算符处断开，那么在该符号前断开(比如+，它将位于下一行)。注意：这一点与Google其它语言的编程风格不同(如C++和JavaScript)。 这条规则也适用于以下“类运算符”符号：点分隔符(.)，类型界限中的&（
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[]。
- swtich语句
缩进
与其它块状结构一致，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语句组，即使它什么代码也不包含。
- 注解
注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。这些换行不属于自动换行(第4.5节，自动换行)，因此缩进级别不变。例如：
@Override
@Nullable
public String getNameIfPresent() { ... }
例外：单个的注解可以和签名的第一行出现在同一行。例如：
@Override public int hashCode() { ... }
应用于字段的注解紧随文档块出现，应用于字段的多个注解允许与字段出现在同一行。例如：
@Partial @Mock DataLoader loader;参数和局部变量注解没有特定规则。
- 注释
块注释风格
块注释与其周围的代码在同一缩进级别。它们可以是/* … /风格，也可以是// …风格。对于多行的/ … /注释，后续行必须从开始， 并且与前一行的*对齐。以下示例注释都是OK的。
/*
* This is // And so /* Or you can
* okay. // is this. * even do this. */
*/
注释不要封闭在由星号或其它字符绘制的框架里。
- Modifiers
类和成员的modifiers如果存在，则按Java语言规范中推荐的顺序出现。
public protected private abstract static final transient volatile synchronized native strictfp
命名约定
- 对所有标识符都通用的规则
标识符只能使用ASCII字母和数字，因此每个有效的标识符名称都能匹配正则表达式\w+。
在Google其它编程语言风格中使用的特殊前缀或后缀，如name_, mName, s_name和kName，在Java编程风格中都不再使用。
- 标识符类型的规则
包名
包名全部小写，连续的单词只是简单地连接起来，不使用下划线。
类名
类名都以UpperCamelCase风格编写。
类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。
测试类的命名以它要测试的类的名称开始，以Test结束。例如，HashTest或HashIntegrationTest
方法名
方法名都以lowerCamelCase风格编写。
方法名通常是动词或动词短语。
下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是：test_，例如testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法
常量名
常量名命名模式为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"};
非常量字段名
非常量字段名以lowerCamelCase风格编写。
这些名字通常是名词或名词短语。
参数名称
参数名以lowerCamelCase风格编写。
参数应该避免用单个字符命名。
局部变量名
局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。
虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。
即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。
类型变量名
类型变量可用以下两种风格之一进行命名：
•单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)。
•以类命名方式(5.2.2节)，后面加个大写的T(如：RequestT, FooBarT)。
- 驼峰式命名法(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*
星号处表示可以，但不推荐。
编程实践
@Override：能用则用
只要是合法的，就把@Override注解给用上。捕获的异常：不能忽视
除了下面的例子，对捕获的异常不做响应是极少正确的。(典型的响应方式是打印日志，或者如果它被认为是不可能的，则把它当作一个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) {
}
- 静态成员：使用类进行调用
使用类名调用静态的类成员，而不是具体某个对象或表达式。
Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad
- Finalizers: 禁用
极少会去重载Object.finalize。
Javadoc
- 格式
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)之前(如果有的话)。 除了第一个段落，每个段落第一个单词前都有标签
，并且它和第一个单词间没有空格。
Javadoc标记
标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。 当描述无法在一行中容纳，连续行需要至少再缩进4个空格
- 摘要片段
每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中。
这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。它不会以A {@code Foo} is a…或This method returns…开头, 它也不会是一个完整的祈使句，如Save the record…。然而，由于开头大写及被加了标点，它看起来就像是个完整的句子。
- 哪里需要使用Javadoc
至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：
例外：不言自明的方法
对于简单明显的方法如getFoo，Javadoc是可选的(即，是可以不写的)。这种情况下除了写“Returns the foo”，确实也没有什么值得写了。
单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。
例外：重载
如果一个方法重载了超类中的方法，那么Javadoc并非必需的。
可选的Javadoc
对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为， 那么这个注释应该写成Javadoc，这样更统一更友好。
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
