Java Development Specification Summary _ Code Comment specification

The norm needs to be noticed in the regular coding process, which is a good habit to develop slowly.

1. Basic rules

1. Comments should make the code more readable
2. Note to be simple and straightforward, just provide the information necessary to clearly understand the procedure. If the comment is too complex, the program needs to modify the adjustment to make the design more reasonable.
3. Note Not only describes what the program does, but also describes why to do so, as well as the constraints
4. For the general getter, setter method without comment
5. Annotations cannot be nested
6. The need to generate the development documentation is written in Chinese

2. Three ways to annotate

1. Documentation Comments/** */

You can use multiple lines, which are generally used to describe classes, interfaces, member methods, member variables, static fields, static methods, constants. Javadoc can use it to generate code for the document. For readability, you can have indentation and formatting controls.
Document annotations often use tags to describe specific uses of a document to help Javadoc produce documents that are commonly used:

Label	Used for	Objective
@author Name	Class/interface	Describe the author of the Code, and each author corresponds to one such label
@deprecated	Class Member Methods	Indicates that the API has been revoked
@exception Name Description Or @throws Name Description	Member Methods	Describes the exception that the method throws Each exception one corresponds to one such label
@param name Description	Member Methods	Describes the purpose and meaning of a parameter in a member method, and one parameter corresponds to one such label
@return Description	Member Methods	Describe the meaning of the return value of a member method
@since	Class/interface Member Methods	Describe when the API started
@see ClassName	Class/interface Member Methods Member variables	Used to refer to a specific class description, general classname with full name including the package name
@see classname#memberfunction	Class/interface Member Methods Member variables	A description of the member method used to refer to a particular class, typically classname with the full name of the package name
@version text	Class/interface	Version
@inheritDoc	Class/interface Member Methods	Inherited documents

2. Line Comment//

Can only comment one line at a time, generally used to briefly describe a local variable, the role of the program block

3. Block Comment:/* */

Prohibit use of in code

4. Class/Interface annotations

Class/Interface Description, generally more detailed. In the usual order of instructions, mainly including
1. The main description of the class, in. Or. End
2. Target of class design, what function to accomplish
3.<strong> Main classes use </Strong> How to use this class, including environmental requirements, such as whether thread safety, concurrency requirements, and the use of constraints
4.<strong> known Bug</strong>
5. Description of the modification history of the class:<strong> + date + simple description </Strong>
[email protected] Author, @version version, @see reference, @since start version and other information such as:

/*** This class provides default implementations for the JFC <code>Action</code> * interface. Standard behaviors like the get and set methods for * <code>Action</code> Object Properties (icon, text, and E nabled) is defined * here.  The developer need only subclass this abstract class and * Define the <code>actionPerformed</code> method. * <p> * <strong>Warning:</strong> * Serialized objects of this class is not being compatible with * Futu  Re Swing releases. The current serialization are appropriate * for short term storage or RMI between applications running the same * V  Ersion of Swing. A future release of Swing would provide support for * long term persistence. * * @version1.41 2015/05/26 *@authorxxxxx *@seeAction*/

In order to make the resulting document readable, annotations often have indentation and formatting controls. The class description is placed immediately before the class definition of the class and cannot have any empty rows.

3. Variable annotations

1. member variables, class static variables take documentation comments, and comments on member variables usually include:
1) The meaning of variables
2) The legal domain value of the variable
3) Restrictions on concurrent access
Such as:

/***/public    finalstatic String app_config = "Aaa.uiapp ";

2. Local variables, such as algorithm-dependent variables with block or line annotations

 Public void   func () {    int// used for loop count .....     }

3. Parameter variable annotations are generally annotated with a document and are described as parameters using @param, which generally includes

1) Use of parameters

2) requirements for range of parameter values

4. Method notes

Describes the functions of a function, for member methods, static methods are generally used in document description, especially public methods. Comments can be very detailed and can contain formatting controls for readability, as the following description contains indents:

/** * Here are a method comment with some very special* formatting that I want indent (1) to ignore.* */

Method annotations generally include:
1. The main description of the method, in. Or. End
2. Describe how the method accomplishes the purpose of the method, and the reason for using the method
3. Describe how the method is used, including the environmental requirements used, such as preconditions, post conditions, and concurrency requirements
4. Description of known bugs
5. Modification History of Description method:<strong> + Date + simple description </Strong> (< modifier + Date + simple description >)
[email protected] C elements to is inserted into the This list. (parameter description)
[Email protected] <tt>true</tt> If this list changed as a result of the call. (return value description)
[Email protected] NullPointerException If the specified Collection is null. (Exception description)
[Email protected] If the overloaded method must refer to the method of the parent class
The return value of the Javadoc description method with Alt+shift+j generated under 10Eclips ((@return)

5. Modify the Record

1. Before modifying a class, you must update it from SVN and then modify it.
2. Modify the place must be added to the note, indicating the modification of the person, the reason for modification, modify the content, modify the time;

Java Development Specification Summary _ Code Comment specification