欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

【Java/代码风格】编程风格规范

程序员文章站 2022-03-31 09:36:02
...


  前几天在gitbook上翻到Google的[Java代码编程风格规范](https://legacy.gitbook.com/book/jervyshi/google-java-styleguide-zh/details),花了些时间阅读,觉得非常有收获。 本着好记性不如烂笔头的老生常谈,我将其中常用部分内容摘录出来做成笔记,以备后查。


一、准确的命名标识符

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

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

 2.标识符类型的规则

  2.1包名

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

类名

   类名都以UpperCamelCase风格编写,通常是名词或名词短语;接口名称有时可能是形容词或形容词短语
    测试类的命名以它要测试的类的名称开始,Test结束。例如,HashTestHashIntegrationTest

  2.2方法名

    方法名都以lowerCamelCase风格编写,,通常是动词或动词短语;下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是:test<MethodUnderTest>_<state>,例如testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法。

  2.3常量名

    常量名命名模式为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"};
  2.4非常量字段名

    非常量字段名以lowerCamelCase风格编写。这些名字通常是名词或名词短语

  2.5参数名

    参数名以lowerCamelCase风格编写,参数应该避免用单个字符命名

  2.6局部变量名

    局部变量名以lowerCamelCase风格编写,比起其它类型的名称,局部变量名可以有更为宽松的缩写。
    虽然缩写更宽松,但还是要避免用单字符进行命名,除了临时变量和循环变量。
    即使局部变量是final和不可改变的,也不应该把它示为常量,自然也不能用常量的规则去命名它

  2.7类型变量名

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

  a)单个的大写字母,后面可以跟一个数字(如:E, T, X, T2)。
  b)以类命名方式,后面加个大写的T(如:RequestT, FooBarT)。

  2.8驼峰式命名法(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*
    

    注意:在英语中,某些带有连字符的单词形式不唯一。例如:”nonempty”和”non-empty”都是正确的,因此方法名checkNonemptycheckNonEmpty也都是正确的。



二、正确的换行

  一般情况下,写一行长代码为了避免超出列限制(80或100个字符)而被分为多行的情况,我们称之为自动换行(line-wrapping)
  自动换行后至少缩进4个空格,第一行后的每一行至少比第一行多缩进4个空格;但注意,制表符是不用于缩进的,正确做法应该是使用ASCII水平空格字符(0x20,即空格) 进行格式缩进。

自动换行的基本准则是:

  1. 如果在非赋值运算符处断开,那么在该符号前断开(比如+,它将位于下一行)
  2. 如果在赋值运算符处断开,通常的做法是在该符号后断开(比如=,它与前面的内容留在同一行。这条规则也适用于foreach语 句中的分号)
  3. 方法名或构造函数名与左括号留在同一行
  4. 逗号(,)与前面的内容留在同一行

  当存在连续自动换行时 ,缩进可能会缩进不只4个空格(语法元素存在多级时)。一般而言,两个连续使用相同的缩进当且仅当他们开始于同级语法元素



三、对括号的处理

 1.使用大括号(即使是可选的)

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

 2. 非空块(K & B 风格)

   对于非空块和块状结构,大括号遵循Kernighan和Ritchie风格
   即:

  a)左大括号前不换行
  b)左大括号后换行
  c)右大括号前换行
  d)如果右大括号是一个语句、函数体或类的终止,则右大括号后换行,否则不换行。例如,如果右大括号后面是else或逗号,则不换行

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

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

void doNothing(){};
 3.用小括号来限定组(推荐!)

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



四、Javadoc格式规范

 1.格式

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

  1.2段落

  空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。 除了第一个段落,每个段落第一个单词前都有标签<p>,并且它和第一个单词间没有空格。

  1.3Javadoc标记

   标准的Javadoc标记按以下顺序出现:@param, @return, @throws, @deprecated, 前面这4种标记如果出现,描述都不能为空。 当描述无法在一行中容纳,连续行需要至少再缩进4个空格

  1.4摘要片段

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

Tip:一个常见的错误是把简单的Javadoc写成/** @return the customer ID */,这是不正确的。它应该写成/** Returns the customer ID. */


 2.哪里需要使用Javadoc

  至少在每个public类及它的每个public和protected成员处使用Javadoc,以下是一些例外:

   2.1例外:不可言明的方法

     对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了写“Returns the foo”,确实也没有什么值得写了。
     单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。

Tip:如果有一些相关信息是需要读者了解的,那么以上的例外不应作为忽视这些信息的理由。例如,对于方法名getCanonicalName, 就不应该忽视文档说明,因为读者很可能不知道词语canonical name指的是什么。

   2.2例外:重载

    如果一个方法重载了超类中的方法,那么Javadoc并非必需的。

   2.3例外:可选的Javadoc

    对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为, 那么这个注释应该写成Javadoc,这样更统一更友好。



五、其他

 1.文件编码

  源文件编码设置为为UTF-8

 2.文件名字

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

 3.源文件结构

  一个源文件包含(按顺序地):

  a)许可证或版权信息(如有需要)
  b)pack语句
  c)import语句
  d)一个*类(只有一个

  以上每个部分之间用一个空行隔开

  3.1 许可证或版权信息

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

  3.2 package语句

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

  3.3 import语句
   3.3.1 import不要使用通配符

    不要出现类似这样地import语句:import java.util.*;

   3.3.2 不要换行

    import语句不换行,列限制并不适用于import语句(每个import语句独立成行)

   3.3.3 顺序和间距

    import语句可分为以下几组,按照这个顺序,没组有一个空行分隔

    a)所有的静态导入独立成组
    b)com.google import (仅当这个源文件实在com.google包下)
    c) 第三方地包。每个*包为一个组;字典序。例如:android,com,junit,org,sun
    d)java imports
    e)javax imports

  注意:组内不空行,按字典序排列

 4.类声明

  4.1只有一个*类声明

    每个*类都在一个与它同名的源文件中(当然,还包含.java后缀)
    例外:packge-info.java,该文件中可没有package-info类(此文件不可被随便创建)

  4.2类成员顺序

    类的成员顺序对易学性有很大的影响,但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。最重要的一点,每个类应该以某种逻辑取排序他的成员,维护者应该要能解释这种排序逻辑。
    比如:当引得方法不能总是习惯性的添加到类的结尾,因为这样就是按照时间顺序而非某种逻辑来排列

 重载:当一个类有多个构造函数,或是多个同名方法,这些函数/方法应该按顺序出现在一起,中间不要放进其他函数/方法





                                                字   数:5645
                                                用   时:3h
                                                完成时间:2020年04月22日