Java code comment specification of Power node collation

Code annotation serves as a communication bridge between program designer and program reader to maximize the efficiency of team development cooperation. It is also an important part of the maintainability of the program code. So we're not commenting for the sake of commenting. The following is the code comment specification we use in daily development for your reference.

1. Annotation form 1

Throughout the application, annotations are constructed using a style with 1-point punctuation and structure. If you find in other projects that their annotation specifications are different from this document, write code according to this specification, and do not attempt to introduce a new specification into the established specification system.

2. The content of the notes is accurate and concise

Content to be simple, clear, accurate meaning, to prevent the ambiguity of comments, wrong comments not only useless but harmful.

Annotation conditions:

1. Basic comments

(a) class (interface)

(b) constructor annotation

(c) method annotation

(d) comments for global variables

(e) comments for fields/properties

Note: Simple code can be simply commented with no more than 10 words. In addition, the getter and setter methods of the persistent object or VO object need not be commented. Please refer to the following example for the specific annotation format.

2, special must be annotated

Typical algorithms must be annotated.

(b) Must have comments where the code is unclear.

(c) Add comments where code changes are made to modify the identity.

(d) add comments to code that consists of loops and logical branches.

Interfaces provided to others must be annotated in detail.

Note: There is no example for this type of annotation format. The specific annotation format is defined by itself, which requires the annotation content to be accurate and concise.

Comment format:

1. Single line (single-ES57en) note: "//..."

2. Block (block) note: "/*... * /"

3. Document comment: "/**... * /"

4, javadoc annotation tag syntax

The @author description of the class identifies the author who developed the module
The @ES70en description of the class indicates the version of the module for that class
see refers to classes, properties, methods, and related topics
Description of a method description of a parameter in a method
return description of a method description of a method return value
exception describes exceptions that a method's specification might throw

Reference examples:

1. Class (interface) comments

Such as:

/**
*  The description of the class 
* @author Administrator
* @Time 2016-11-14:49:01
*
*/
public classTest extends Button {
  ... 
}

2. Constructor annotations

Such as:

public class Test extends Button {
 /**
 *  A constructor   A description of the 
 * @param name
 *  The text displayed on the button 
 */
 public Test(String name){
  ... 
 }
}

3. Method annotations

For example,

public class Test extends Button {
 /**
 *  Add color to the button 
 *@param color
   Button color 
*@return
*@exception ( Method if there is an exception )
* @author Administrator
* @Time2012-11-20 15:02:29
 */
 public voidaddColor(String color){
  ... 
 }
}

4. Global variable annotation

Such as:

public final class String
 implements Java.io.Serializable, Comparable<String>,CharSequence
{
 /** The value is used for characterstorage. */
 private final char value[];
 /** The offset is the first index of thestorage that is used. */
 private final int offset;
 /** The count is the number of charactersin the String. */
 private final int count;
 /** Cache the hash code for the string */
private int hash; // Default to 0
 ... 
}

5. Field/property comments

Such as:

public class EmailBody implements Serializable{
 private String id;
 private String senderName;// Sender's name 
 private String title;// No more than 120 Chinese characters 
 private String content;// Email body 
 private String attach;// Attachments, if any 
 private String totalCount;// Total number of senders 
 private String successCount;// Number of successful senders 
 private Integer isDelete;//0 Don't delete  1 delete 
 private Date createTime;// Timing is not currently supported   So send it immediately after it's created 
 privateSet<EmailList> EmailList;
 ... 
}

In fact, the specification is made by oneself, as long as everyone in the team all abide by the unified 1 standard, it will achieve good results, I hope to help friends who do not add notes at ordinary times.