Java code comment specification of Power node collation
- 2020-06-15 09:06:02
- OfStack
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.