Detailed explanation of Java code comment specifications (power node organization)

CodeComments is a communication bridge between program designers and program readers, maximizing the efficiency of team development cooperation. It is also one of the important aspects of program code maintainability. Let’s talk about the code comment specifications we use in daily development through this article

Code comments are a communication bridge between program designers and program readers, maximizing the efficiency of team development cooperation. It is also one of the important aspects of program code maintainability. So we don't write comments for the sake of writing comments. Let’s talk about the code comment specifications we use in daily development for your reference.

1. Uniform comment form

Construct comments using a style with consistent punctuation and structure throughout the application. If you find that their annotation specifications in other projects are different from this document, write code according to this specification and do not try to introduce new specifications into the established specification system.

2. The annotation content should be accurate and concise

The content should be simple, clear, and accurate in meaning to prevent ambiguity in the annotation. Wrong annotation It is not helpful but harmful.

Comment conditions:

1. Basic comments

(a) Class (Interface) Comments

(b) ConstructorComments

(c) Method comments

(d) GlobalComments for variables

(e) Comments for fields/attributes

Note: Simple comments should be made for simple codes, and the comment content should not exceed 10 words. That's it. In addition, the getter and setter methods of the persistent object or VO object do not need to be annotated. Please refer to the example below for the specific comment format.

2. Special comments must be added

(a) Typical algorithms must have comments.

(b) There must be comments where the code is unclear.

(c) Add a comment indicating the modification to the code modification.

(d) Add comments in the code consisting of loop and logical branches.

(e) The interface provided for others must be commented in detail.

Note: There are no examples of this type of comment format yet. The specific annotation format is defined by yourself, and the annotation content is required to be accurate and concise.

Comment format:

1. Single-line comment: “//……”

2. Block comment: “/*&*/”

3. Document comment: “/**&*/”

4. Javadoc comment tag syntax

@author The description of the class indicates the author who developed the module of this type
@version The description of the class indicates the version of the module of this type
@see The description of the class, attributes, and methods refers to the steering. That is, related topics
@param Description of the method Description of a parameter in the method
@return Description of the method Description of the return value of the method
@exception Description of the method Describes the exceptions that may be thrown by the method

Reference example:

1. Class (interface ) Comment

For example:

/**
* 类的描述
* @author Administrator
* @Time 2016-11-14:49:01
*
*/
public classTest extends Button {
 ……
}

2. Construction method Comment

For example:

public class Test extends Button {
 /**
 * 构造方法 的描述
 * @param name
 * 按钮的上显示的文字
 */
 public Test(String name){
 ……
 }
}

3. Method comment

For example

public class Test extends Button {
 /**
 * 为按钮添加颜色
 *@param color
  按钮的颜色
*@return
*@exception (方法有异常的话加)
* @author Administrator
* @Time2012-11-20 15:02:29
 */
 public voidaddColor(String color){
 ……
 }
}

4. Global variable comment

For example:

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/attribute comments

For example:

public class EmailBody implements Serializable{
 private String id;
 private String senderName;//发送人姓名
 private String title;//不能超过120个中文字符
 private String content;//邮件正文
 private String attach;//附件，如果有的话
 private String totalCount;//总发送人数
 private String successCount;//成功发送的人数
 private Integer isDelete;//0不删除 1删除
 private Date createTime;//目前不支持定时 所以创建后即刻发送
 privateSet<EmailList> EmailList;
……
}

In fact, the specifications are set by ourselves. As long as everyone in the team abides by them and unifies the specifications, we will get Good effect, I hope it will be helpful to friends who usually don’t comment.

The above is the detailed content of Detailed explanation of Java code comment specifications (power node organization). For more information, please follow other related articles on the PHP Chinese website!