Naming Conventions in Java (代码规范，命名规则)

 

Naming Convention in Java (代码规范，命名规则)

General rules: 

CamelCase/camelCase (mixed case) 

 CamelCase

camelCase

Ref: https://en.wikipedia.org/wiki/Camel_case

Camel case (sometimes stylized as camelCase or CamelCase, also known as camel caps or more formally as medial capitals) is the practice of writing phrases without spaces or punctuation and with capitalized words. The format indicates the first word starting with either case, then the following words having an initial uppercase letter. Common examples include "YouTube", "iPhone" and "eBay". Camel case is often used as a naming convention in computer programming. It is also sometimes used in online usernames such as "JohnSmith", and to make multi-word domain names more legible, for example in promoting "EasyWidgetCompany.com".

The more specific terms Pascal case and upper camel case refer to a joined phrase where the first letter of each word is capitalized, including the initial letter of the first word. Similarly, lower camel case (also known as dromedary case) requires an initial lowercase letter. Some people and organizations, notably Microsoft, use the term camel case only for lower camel case, designating Pascal case for the upper camel case.

Snake case

snake_case

Snake case (stylized as snake_case) refers to the style of writing in which each space is replaced with an underscore (_) character, and the first letter of each word is written in lowercase. It is a commonly used naming convention in computing, for example for variable and subroutine names, and for filenames. One study has found that readers can recognize snake case values more quickly than camel case.

Why Have Code Conventions

Code conventions are important to programmers for a number of reasons:

• 80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
• If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html

• 一个软件需要花费80%的生命周期成本去维护。 　　
• 几乎没有任何软件的整个生命周期仅由其原作者来维护。 　　
• 编码规范改善软件的可读性,让工程师更快更彻底地理解新的代码。 　　
• 如果你将源代码转变为一个产品,那么您需要确保它和你创建的其它产品一样是干净且包装良好的。

Java

             Readability counts

Naming Conventions 命名规则

业界有一句话也许大部分程序员都认同：“代码就是最好的注释”，而好的命名有利于增强代码的可读性。为了增强代码的可读性，命名应遵从三个原则：

• 共识：共识是指不同人的横向比较，共识按范围分包含组内共识（业务相关的专有名词）、企业内部公司和业界共识；
• 统一：统一是指单个人的垂直比较，单个人在不同时间点编写的变量、方法、类的命名要统一，不能出现同一个概念一会儿这样命名，一会儿又那样命名；命名不同意也会加大代码阅读难度；
• 得体：得体是指用词合理，做到词能达意，命名能够很好地表达用意（类命名一般是名词短语，方法命名一般是动词短语）；

代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

• Names to avoid

Never use the characters ‘l’ (lowercase letter el), ‘O’ (uppercase letter oh), or ‘I’ (uppercase letter eye) as single-character variable names.

In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use ‘l’, use ‘L’ instead.

• Method, parameters, variables, local variable names 方法名、参数名、成员变量、局部变量命名

方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

变量名应该简短且有意义，并能够顾名思义。简单并不意味着越短越好，比如一个字符的变量名是不允许的，很影响代码的可读性。

对于局部变量，为了保证代码简洁，局部变量命名只要能够在代码中区分，应避免名称过长，影响阅读。

• Class Names 类命名

Class names should normally use the UppperCamelCase convention.

类名使用 UpperCamelCase 风格，必须遵从驼峰形式

Examples:

       ArrayList

                FixedSizeList 

                LinkedList 

• Package name 包命名

包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

• File name

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

• Encoding

源文件编码格式为UTF-8

• Constants 常量命名

Constants are usually defined on a module level and written in all capital letters with underscores separating words. Examples include MAX_OVERFLOW and TOTAL.

常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

常量是用final修饰符修饰的不可变数值基础类型（或数值类型），本节可讨论话题不多，笔者想强调4点：

1. 在工程中不要使用一个常量类维护所有常量。
2. 常量类请加修饰符final以表示他是不可继承的。
3. 合理地放置常量类，即区分是类内部常量，还是包内常量，还是是整个工程常量。
4. 几个具有相关性的常量（比如type，state）请使用枚举。

合理地放置常量类，正确的做法是：

• 跨应用共享常量，放在准备提供给外部jar包所在module的consts目录；
• 工程内共享常量，放在工程common module下consts目录；
• 子模块内部共享，在相应子模块consts目录；
• 类内共享，放在类内部，注意加private进行限定；

Source File Structure

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

1. 许可证或版权信息(如有需要)
2. package语句
3. import语句
4. 一个顶级类(只有一个)

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

import不要使用通配符 (import java.util.*;)

import语句不换行

import语句可分为以下几组，按照这个顺序，每组由一个空行分隔：

• 所有的静态导入独立成组
• com.google imports(仅当这个源文件是在com.google包下)
• 第三方的包。每个顶级包为一组，字典序。例如：android, com, junit, org, sun
• java imports
• javax imports

组内不空行，按字典序排列。

类声明

每个顶级类都在一个与它同名的源文件中(当然，还包含.java后缀)。

例外：package-info.java，该文件中可没有package-info类。

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

大括号

对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格 (Egyptian brackets):

• 左大括号前不换行
• 左大括号后换行
• 右大括号前换行
• 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。例如，如果右大括号后面是else或逗号，则不换行。

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

Comments 注释

注释有利于帮助理解代码，如果使用不当，反而会影响代码的简洁性，不利于理解代码。注释在使用上笔者认为需要坚持三个原则：

保持代码干净，消除不必要的注释：好的代码本身就是最好的注释，只在必要时通过注释协助理解代码，目的是保持代码的简洁性，增强代码的可读性；

区分注释和JavaDoc：类、域、方法使用JavaDoc，方法内部使用注释；

注释及时更新：注释也是代码的一部分，如果代码发生变更，注释也要跟着改；

注释掉的是代码，将来可能还需要还原，如果确实是这种情况，那么完全可以通过版本控制工具（git or svn）还原。

Reference

https://hawstein.com/2014/01/20/google-java-style/