软件流程规范—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;   /**  *  * 类描述:Just a demo  *  *  * @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_，例如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.  配置”保存时自动格式化”

 

文章知识点与官方知识档案匹配，可进一步学习相关知识Java技能树首页概览91518 人正在系统学习中

来源：17奋斗8