软件流程规范---java代码规范

1.    介绍

采用 Google推出的Java代码规范。

Google Java代码规范原文：https://google.github.io/styleguide/javaguide.html

Google Java 代码规范中文版：http://segmentfault.com/a/1190000002761014

 

此文档主要侧重于有明确标准，必须遵守的规范说明。

至于代码格式，会提供Google  Java代码样式格式化模板（见 代码样式模板 章节）将之导入到Eclipse后，即可将现有代码格式标准化。

2.    必须遵守的规范项说明

2.1.    源文件基础

2.1.1.   文件名

源文件与其最顶层类名完全一致，文件扩展名为“.java”。

2.1.2.   文件编码

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

2.2.    源文件结构

一个源文件按顺序包含：

1，  许可证或版权信息

2，  package语句

3，  import 语句

4，  唯一一个顶层类

 

示例：

/**

 * Copyright (C) 2

 */

package com.xx.formmaterdemo;

 

import java.math.BigDecimal;

 

/**

 * <p>

 * 类描述:Just a demo

 * </p>

 *

 * @Date 2015年12月30日上午11:34:56

 */

public class FormatterDemo {

 

    public void doXxx()  {

       System.out.println(BigDecimal.ZERO);

    }

}

 

2.2.1.   import语句

不能在import语句中使用通配符。例如：

2.2.2.   类声明

1， 成员变量(Fields)声明在构造函数和成员方法（Methods）声明之前；构造函数声明在其他成员方法声明之前

 

例如，下例中”field2”声明的位置是错误的；构造函数的位置也是错误的。

public class FormatterDemo {

   

    private int field1 = 0;

 

    public void doXxx()  {

       System.out.println(BigDecimal.ZERO);

    }

   

    private int field2 = 0;

   

    public FormatterDemo( ) {

        //TODO:

    }

}

 

2， 类重载(overload)方法：不分离

 

当一个类有多个构造函数或有多个同名（即重载）方法时，这些函数/方法应该出现在一起，中间不能放进其他代码。

例如，下例中”doZzz”方法声明的位置是错误的。

    public void doYyy( int a ) {

        //TODO

    }

   

    public void doZzz( ) {

        //TODO

    }

   

    public void doYyy( int a,int b) {

        //TODO

    }

2.3.    命名

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

标识符只能使用26个英文字母、数字和下划线（"_”）。

2.3.2.   包名(package)

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

例如spring的包名是以 com.springframework 打头而不是com.spring_framework。

每个项目都应该有独立的包名，一般以com.pingan.qhzx.projectname构成。

2.3.3.   驼峰式命名法

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

2.3.4.   类名(Class)

类名都以UpperCameCase（首字母大写的驼峰风格）编写。

类名通常都是名词（如Character）或名词短语（如ImmutableList）。接口除名词外也可以是形容词或形容词短语（如Readable）。

测试类的命名以它要测试的类的名称开始，以Test结束。例如 HashTest或HashIntegrationTest。

2.3.5.   方法名(Method)

方法名都以lowerCamelCase（首字母小写的驼峰风格）编写。

方法名通常是动词或动词短语。

下划线可出现在JUnit测试方法名称中用以分隔目标类的待测试方法和测试场景。一个典型的模式是：test<MethodUnderTest>_<state>，例如testPop_emptyStack。并不存在唯一正确的方式来命名测试方法。

2.3.6.   常量名

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

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

2.3.7.   非常量成员变量名

以lowerCamelCase风格编写。

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

2.3.8.   参数名

参数名以lowerCamelCase风格编写。

参数应该避免用单个字符命名。

2.3.9.   局部变量名

局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。但还是要避免用单字符进行命名，除了临时变量和循环变量。

2.3.10.类型变量名

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

1，单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)。

2，以类命名方式，后面加个大写的T(如：RequestT, FooBarT)。

譬如

2.4.    编程实践

2.4.1.   变量声明

1， 每次只声明一个变量

不要使用组合声明，例如

2， 需要时才声明，并尽快初始化

不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。

3， 非C风格的数组声明

中括号是类型的一部分。数组变量声明采用类似于String[] args的形式， 而非String args[]。

 

2.4.2.   switch语句

在一个switch块内，每个语句组要么通过break, continue, return或抛出异常来终止，要么通过一条注释来说明程序将继续执行到下一个语句组（任何能表达这个意思的注释都是OK的，典型的是用// fall through)。

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

示例：

switch (input) {

 case1:

     //fall through

 case2:

prepareOneOrTwo();

//fall through

 case3:

    handleOneTwoOrThree();

   break;

 default:

    handleLargeNumber(input);

}

2.4.3.   使用大括号“{”，即使是可选的

大括号与if, else, for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。

    //bad

       if ( condition1 )

            doXxx();

        else

        doYyy();

 

//good

       if ( condition1 ) {

            doXxx();

} else {

    doYyy();

}

     

2.4.4.      使用小括号“(”，即使是可选的

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

 

//good

(a * b) |(2+(c%d))

basePrice* (normalDiscount - (1 - extraDiscount)) * marketDiscount

 

//bad

a*b|2+c%d

basePrice* (normalDiscount + extraDiscount - 1) * marketDiscount

2.4.5.   静态成员，使用类进行调用

Foo aFoo = ...;

Foo.aStaticMethod();// good

aFoo.aStaticMethod();// bad

somethingThatYieldsAFoo().aStaticMethod();// very bad

2.4.6.   @Override：能用则用

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

2.4.7.   异常处理

1，  捕获的异常，一般都需要处理（记日志/处理/抛出）；如果的确可忽略，一定要加注释说明原因。

例如

try {

 int i = Integer.parseInt(response);

 return handleNumericResponse(i);

}catch (NumberFormatException ok) {

 // it's not numeric; that's fine, justcontinue

}

returnhandleTextResponse(response);

2，  输出异常日志，切忌忽略堆栈

logger.error(“Exception happened for order:{}:” + e.getMessage(), orderId);// bad

logger.error(“Exception happened for order:{}”, orderId, e); //good

2.4.8.   日志

1，  日志输出建议用英文

2，  输出日志一定要带关键业务定位信息，譬如订单ID等。

3.    代码样式模板

3.1.    格式化模板

在Google标准格式化模板基础上将缩进调整为4个空格而成（Google的缩进标准是2个空格）。

Eclipse导入方法：“Windows”->“Preference”->”Java”->”CodeStyle”->”Formatter”->”Import…”

导入后，格式化代码：Ctrl+Shift+F或 “Source”->”Format”

3.2.    代码模板

主要用于新建类时，自动生成版权信息/作者/日期等。

Eclipse导入方法：“Windows”->“Preference”->”Java”->”CodeStyle”->”Code Template”->”Import…”，导入前，务必勾选 “Automatically addcomments for new methods and types”

 

 

示例：

 

3.1.  配置”保存时自动格式化”