Farewell coding 5 minutes, naming 2 hours! The most complete Java naming convention reference ever!

A clean, clean code style should be what most engineers expect. At work, I often struggle with naming. To exaggerate, it takes 5 minutes to program and 2 hours to name. Exactly why naming becomes a stumbling block in the work.

Each company has different standards to maintain uniformity, reduce communication costs and improve team r&d effectiveness. Therefore, this article is the author combined with Alibaba development specifications, as well as the work experience for the Java field related naming arrangement and summary, for reference only.

First, naming conventions in Java

Good naming can reflect the character, meaning, or purpose of the code, allowing the reader to quickly clarify the context of the program based on the meaning of the name. In Java, there are three common naming forms: UpperCamelCase (uppercase), lowerCamelCase (lower case), and UPPER_CAMEL_UNSER_SCORE (all uppercases and underscores). By convention, classes are generally named with a big camel, methods and local variables are named with a small camel, and uppercase underline is usually used in constants and enumerations.

Two, package naming

The package names are all lowercase, and there is only one or more natural semantic English words between the dot delimiters, or more words are naturally connected together (for example, springframework and deepspace do not need to use any division). The package name must be singular. If the class name has a plural, it can be plural.

Package name can be divided into the following four parts [prefix] [initiator name] [project name] [module name]. Common prefixes can be classified as follows:

Third, class naming

In addition to nouns and noun phrases, interface names can also use adjectives or adjective phrases, such as Cloneable, Callable, etc., to indicate that the class that implements the interface has certain functions or capabilities. For a Test class, it starts with the class it is testing and ends with Test, such as HashMapTest.

It is also possible to use all caps for abbreviations of specific nouns, such as XMLHttpRequest, but I believe that abbreviations should be capitalized up to three letters, or more. There is no standard such as Fastjson in Alibaba, which uses JSONObject as the name of the class, and Google uses JsonObjectRequest. For this special abbreviation, the principle is unified.

Four, the method

Method names are small humps, with the first letter in lower case and each subsequent word capitalized. Unlike class names, method names are usually verbs or phrasal verbs, which together with parameters or parameter names form verb-object phrases, i.e., verbs + nouns. A good function name usually tells you directly what the function does.

4.1 Method of returning true and false values

Note: Prefix- Prefix, Suffix- Suffix, Alone- used Alone

4.2 Methods used for inspection

4.3 The on-demand approach

4.4 Asynchronous Related methods

4.5 Callback method

4.6 Methods of operating the object life cycle

4.7 Methods related to collection operations

4.8 Methods related to data

4.9 Pairs of verbs

Fifth, variable & constant naming

5.1 Variable Naming

Variables are variables whose values can be changed during program execution, including member variables and local variables. When a variable name consists of multiple words, the first letter of the first word is lowercase and the first letter of the following words is uppercase, commonly known as camel naming (also known as camel naming), such as computedValues, index, variable naming, as short as possible to clearly express the function of the variable, the name reflects the specific business meaning.

Variable names should not begin with an underscore or dollar sign, although this is syntactically permissible. Variable names should be short and descriptive. Variable names should be chosen to be easy to remember, that is, to indicate their purpose. Avoid single-character variable names unless they are one-time temporary variables. Pojo Boolean variables should not be prefixed with is(all Boolean fields in the database should be prefixed with IS_).

5.2 Constant Naming

Constants are named CONSTANT_CASE, usually in all capitals (except when used as method parameters), and words are separated by underscores. So what is a constant?

Constants are values that remain constant in scope and are typically modified with final. There are three types of constants: global (public static final), internal (private static final), and local (constant within a method or parameter). Local constants are special, and are usually named with a small hump.

/** * a demo **@author Jann Lee
 * @dateThe 2019-12-07 00:25 * * /
public class HelloWorld {

    /** * global constant (positive example) */
    public static final long USER_MESSAGE_CACHE_EXPIRE_TIME = 3600;
    
      /** * global constant */
    public static final long MESSAGE_CACHE_TIME = 3600;
    
    /**
     * 局部常量
     */
    private static final String ERROR_MESSAGE = " error message";

    /** * member variable */
    private int currentUserId;

    /** * console print {@codeMessage} Message * *@paramMessage Body, local constant */
    public void sayHello(final String message){
        System.out.println("Hello world!"); }}Copy the code

Constants generally have their own business meaning, and don’t be afraid to omit or abbreviate them over time. For example, a representation of the expiration time of the user’s message cache would be clearer and for you to judge.

General naming rules

1. Try not to use pinyin; Avoid mixing pinyin and English. For some general expressions or difficult to describe in English pinyin can be used, once adopted pinyin must not be mixed with English. Example: BeiJing, HangZhou Example: validateCanShu
2. Do not use special characters in the naming process, except constants.
3. Do not use the same name as an existing class in the JDK or framework, and do not use Java keywords.
4. Prepositions such as for(can be replaced by homophone 4), to(can be replaced by homophone 2), from, with, of, etc. For example, the class name is UserService4MySqlDAO, and the method name is getUserInfoFromRedis and convertJson2Map.

Code comments

6.1 Principles of annotations

Good naming makes code readable, and code naming is often strictly restricted. Unlike annotations, programmers are often free to do whatever they want, but that doesn’t mean they can do whatever they want. Elegant annotations usually meet three elements.

1. Nothing is strange unannotated code is very unfriendly to the reader, even if the code is written clean, the reader will be at least psychologically resistant, and there is often a lot of complex logic in the code, so be sure to write annotations, not only to record the logic of the code, but also to clarify the logic of the change.
2. From a code maintenance perspective, comments in code must be the best of the best. Reasonable and clear naming makes code easy to understand. Code with simple logic and naming conventions that clearly express what the code does does not need annotations. Overuse of annotations adds extra burden, not to mention that most of them are nonsense.

// Get information by id
getMessageById(id)
Copy the code

1. Advance with the time annotations should change as the code changes, and the information expressed in the annotations should be exactly the same as in the code. It is common to modify code without modifying annotations.

6.2 Annotation Format

Annotations can be broadly divided into two types, javadoc annotations and simple annotations. Javadoc annotations can be generated to provide effective support for external users through the JavaAPI. Javadoc annotations are automatically generated when using development tools such as IDEA or Eclipse. Custom annotation templates are also supported, requiring only the interpretation of corresponding fields. Students involved in the same project should try to set up the same annotation template.

6.2.1 note after class

In Javadoc annotations, each class must have an annotation.

/** * Copyright (C), 2019-2020, Jann balabala... * * class introduction: this is a used to do what the class, which functions, using the technology..... * *@authorClass creator names remain aligned *@dateKeep the creation date aligned *@versionKeep the version numbers aligned */

Copy the code

6.2.2 Attribute Annotations

Each attribute must be preceded by an attribute comment, usually in one of two forms, whichever you like, but be consistent throughout the project.

/** Prompt message */
private String userName;
/** * Password */
private String password;

Copy the code

6.2.3 Method notes

Each method must be preceded by a method comment that describes each parameter in the method, as well as the return value.

/** ** * /** * * *@paramNote whether the XXX parameter 1 is null *@returnA description of the results returned, and what results will be returned in different cases *@throwsThe exception type specifies how an exception is thrown from such a method
Copy the code

6.2.4 Constructor comments

Each constructor must be preceded by a comment. The comment template looks like this:

/** ** /** * /**@paramNote whether the XXX parameter 1 is null *@throwsThe exception type specifies how an exception is thrown from such a method
Copy the code

While simple annotations often require engineer byte definitions, there are a few things to note when using annotations:

1. Each attribute value of an enumerated class is annotated. Enumerations can be thought of as constants, usually unchanged, and often referred to in multiple places. Modifying and adding attributes to an enumeration often has a big impact.

2. Keep typography clean and don’t use end-of-line comments. Double slashes and asterisks are separated by 1 space.

   int id = 1;Counterexample: Do not use end-of-line comments
   // Counterexample: there is no indentation between a line break and a comment
   int age = 18;
   // Name
   String name;
   /** ** 123 * 2333333 */
   
   Copy the code

References:

Code Efficient

www.cnblogs.com/wangcp-2014…

Qiita.com/KeithYokoma…

Google. Making. IO/styleguide /…

If you are a beginner/intermediate Java developer who is extremely self-taught, follow me on my public account Cruder and make progress together