Java annotation specification sorting

In the process of software development, the annotation specification is always emphasized, but there is no specific standard to describe, usually a few simple statements in the code writing specification, it cannot be used as a standard and basis for code annotation check. Do you have a basis for anything? :) now I have compiled a Java annotation specification. the content comes from the Internet, books, and accumulated content.

Java annotation Specification

Version/status author version date
1.0 ghc 2008-07-02

I. background
1. When we first came into contact with a piece of code, but were asked to effectively analyze the code in a very short time, what kind of annotation information do we need?
2. How can we avoid lengthy and messy comments?
3. In today's collaborative development and maintenance by many people, what notes do we need to ensure high quality and high level development and maintenance work?
Ii. Significance
Annotations in programs are an important means of communication between programmers and readers. The application annotation specification is particularly important for the software itself and software developers. In addition, the concept of converting annotations into code has been put forward in the popular agile development ideas. A good annotation specification can minimize the maintenance cost of a software, and almost no software is maintained by the original developer throughout its lifecycle. Good annotation specifications can improve the readability of the software and allow developers to thoroughly understand the new Code as soon as possible. Good comments can maximize the efficiency of team development cooperation. Long-term normative coding can also enable developers to develop good coding habits and even develop more rigorous thinking capabilities.

Iii. Principles of comments
1. Unified comments
Throughout the application, comments are constructed using styles with consistent punctuation and structures. If other project teams find that their annotation specification is different from this document, write code according to their specification and do not try to introduce new specifications into the existing normative system.

2. concise comments
The content should be simple, clear, and accurate, so as to prevent the ambiguity of comments. Incorrect comments are not helpful but harmful.
3. annotation consistency
You can write comments before writing the code, because you may not have time to do so in the future. In addition, if you have the opportunity to review the code you have written, it seems obvious that six weeks later may not be obvious. Generally, descriptive comments are created before the code, explanatory comments are created during the development process, and prompt comments are created after the code is complete. Modify the corresponding comments while modifying the Code to ensure that the Code is synchronized with the comments.

4. Comment position
Ensure that the annotation is adjacent to the code described by it, that is, the proximity principle of the annotation. Comments to the code should be placed on the top of the adjacent or right side of the Code, not below. Avoid adding comments at the end of the code line. comments at the end of the line make the code harder to read. However, it is appropriate to annotate the variable declaration at the end of the line; in this case, the comment at the end of all lines should be aligned.

5. Number of comments
Annotations are essential, but they should not be too large. In actual code specifications, annotations must account for about 20% of program code. Comments are "prompts" for the Code, rather than documents. Comments in the program cannot be overwhelming. Too many comments will be dazzled, with less comments. Do not write comments passively for writing comments.

6. Delete useless comments
Before code delivery or deployment and release, you must delete temporary or irrelevant comments to avoid confusion in future maintenance work.
7. Complex annotations
If you need to interpret complex code with annotations, check the code to determine whether it should be overwritten. Rewrite the code without comments that are hard to understand. Although the performance should not be sacrificed to make the code simpler and easier to use, the balance between performance and maintainability must be maintained.

8. Additional Comments
It is most useful to describe the relationship between program functions and various components. Low-Level comments that explain how a program works on a row-by-row basis are not conducive to reading, writing, and modifying, it is unnecessary and difficult to maintain. Avoid comments for each line of code. If the code is clear and clear, no comments are added to avoid unnecessary or inappropriate comments.

9. Mandatory comments
A typical algorithm must be annotated. Annotations are required in areas where the code is unclear or cannot be transplanted. Add a comment to the code modification. Add comments to the Code composed of loops and logical branches. To prevent repeated problems, comment out the codes for error fixes and solutions, especially in the team environment.

10. Annotations are ignored during code compilation and are not compiled into the final executable file. Therefore, annotations are not
The size of the executable file is increased.
4. Java annotation skills
1. Empty lines and blank characters are also special comments. Use indentation and empty lines to make code and comments easier
Don't, and coordinate the appearance.
2. When the code is relatively long, especially when there are multiple nesting, in order to make the hierarchy clear, we should
Add comments to the end (comment the start point of the closure after the closed right curly braces). The comments cannot
It can be written very long, as long as it can indicate the end of the control scope of the statement, which is easy to read.
3. Separate the annotation and annotation separator with a space. If there is no color prompt,
This will make the annotations obvious and easy to find.
4. Do not add an external box around the block comment. This may look pretty, but it is difficult to maintain.
5. Each line of comments (together with the code) should not exceed 120 words (1024 × 768), preferably not more than 80
Word (800x600 ).
6. Java Editor (IDE) annotation shortcuts. CTRL +/annotate the current row, and then press it to cancel the comment.
7. For comments of multi-line code, try not to use "/* ...... */", but to use multi-line "//" comments,
This is troublesome, but you do not need to find the pair "/* ...... */" during blocking debugging.
8. Comments are used as code switching switches to temporarily test and block some codes.
Example 1:
//*/
Codesegement1;
//*/
Change the first line:
/*/
Codesegement1;
//*/
Example 2:
// ---------------------- The first paragraph is valid, and the second paragraph is commented out
//*/
Codesegement1;
/*/
Codesegement2;
//*/
You only need to delete the/of the first line to change:
// ------------------------ The first paragraph is commented, and the second paragraph is valid.
/*/
Codesegement1;
/*/
Codesegement2;
//*/
V. Java annotation methods and formats
1. Single-line (single-line) -- short note ://......
Single line comment: a single line comment in the Code. It is better to have a blank line before the comment and have the same indentation level as the subsequent code. If a single row cannot be completed, block comments should be used.
Comment format:/* Comment */

Line header comment: comment at the beginning of the code line. This is mainly to make this line of code meaningless.
Comment format: // comment content

Line-end comment: trailing-a very short comment that comments at the end of the line of the Code. Generally, there are 8 (at least 4) cells left behind the code line, and all comments must be aligned.
Annotation format: code + 8 (at least 4) spaces + // comment content
2. Block -- block annotation :/*...... */
Comment on several lines, which are usually used to provide descriptions of the meaning and purpose of files, methods, and data structures, or descriptions of algorithms. It is usually located in front of a file or method and serves as a guide. It can also be placed in a proper position as needed. This field annotation will not appear in the HTML report. The comment format is generally written as follows:

/*
* Comment content
*/
3. document notes :/**...... */
Comment several lines and write them into the javadoc document. Each document comment will be placed in the comment Separator
In/**... */, the annotation document is used to generate code reports in HTML format.
The file must be written before the class, field, constructor, method, and field definition. The annotation document consists of two parts: Description and block tag. The format of the annotation document is as follows:
/**
* The doget method of the servlet.
* This method is called when a form has its tag Value Method
* Equals to get.
* @ Param request
* The request send by the client to the server
* @ Param response
* The response send by the server to the client
* @ Throws servletexception
* If an error occurred
* @ Throws ioexception
* If an error occurred
*/
Public void doget (httpservletrequest request, httpservletresponse response)
Throws servletexception, ioexception {
Dopost (request, response );
}
Description of the first two actions. After the description is completed, the @ symbol starts with a block flag comment. More Documentation Note
For more information, see javadoc homepage: http://java.sun.com/javadoc/index.html.
4. javadoc annotation label syntax
@ Author the description of the class indicates the author who developed the class module.
@ Version the description of the class indicates the version of the class module.
@ See references to classes, attributes, and methods, that is, related topics
@ Param: Description of a parameter in the other method
@ Return description of the method description of the return value of the Method
@ Exception description of methods description of possible exceptions thrown by methods
6. Java annotation implementation
1. source file comment
Use/*** to annotate the source file /**...... */, You need to comment on the header of each source file, including the file name, file number, version number, author, Creation Time, and file description, including the historical modification records of this file. Chinese annotation template:

/**
* File Name:
* Copyrright (c) 2008-xxxx:
* File number:
* Creator:
* Date:
* Modifier:
* Date:
* Description:
* Version number:
*/

2. Class (module) comments:
Class (module) annotations adopt /**...... */, In the header of each class (module), you must note the necessary information, including: Project name, class (module) number, namespace, JDK version that can run the class, and version number; author; creation time; Class (module) function description (such as function, main algorithm, internal relationship between each part, the relationship between the class and its class, etc, if necessary, there must also be some specific software and hardware requirements), a list of major functions or procedures, and historical modification records of this class (module.

English comment template:
/**
* Copyrright (c) 2008-xxxx: <prospect software forsoft>
* Project: <Project Name>

* Module ID: <(module) class number, which can reference the class number in system design>
* Comments: <for such descriptions, refer to the descriptions in system design>
* JDK version used: <jdk1.6>
* Namespace: <namespace>
* Author: <the author's Chinese name or pinyin abbreviation>
* Create Date: <create date, format: YYYY-MM-DD>
* Modified by: <modifier's Chinese name or pinyin abbreviation>
* Modified Date: <modify date, format: YYYY-MM-DD>
* Why & what is modified <modify reason description>
* Version: <version number>
*/
If the module only modifies a small amount of code, the following notes must be added for each modification:
// Rewriter
// Rewrite Date: <modify Date: Format YYYY-MM-DD> start1:
/* Original code content */
// End1:
Comment out the content of the original code and add the new code with the following comments:
// Added
// Add Date: <add date, format: YYYY-MM-DD> start2:
// End2:
If the input/output parameters or function structure of a module are greatly modified, you must add the following
Note:
// Log ID: <log number, which is added once from 1>
// Depiction: <description of the change>
// Writer: the modifier's Chinese name
// Rewrite Date: <module modification date, format: YYYY-MM-DD>

2. Interface notes:
Use /**...... */The interface comment should contain the purpose of describing the interface, how it should be used, and how it should not be used. The block mark part must contain the author and version. The corresponding implementation class can be annotated without annotations when the interface is clearly annotated.

3. constructor comments:
The constructor uses /**...... */. The description part indicates the role of the constructor. It may not have block tags.
Note TEMPLATE 1:
/**
* Default constructor
*/
Note template 2:
/**
* Description: constructor with parameters,
* Initialization mode name, name, and Data Source Type
* @ Param Schema: schema name
* @ Param name: Name
* @ Param type: Data Source Type
*/

4. Function comments:
Use /**...... */Requires necessary comments before each function or process, including the function or process name, function description, input, output, and return value description; call link and description of called Link. No version (@ version) is allowed in the function comment ).

Note TEMPLATE 1:
/**
* Number of letters:
* Function description:
* Input parameters: <defined by parameters>
* <@ Param followed by a space followed by the variable name of the Parameter
* (Not a type). The space is followed by the description of this parameter.>
*
* Return value:-type <description>
* <Return the void constructor or function,
* @ Return can be omitted. If the return value is an input parameter, the * description must be the same as the @ Param parameter of the input parameter. If necessary, * specify the return value written with special conditions.>

* Unusual: <in alphabetical order of abnormal names>
* Creator:
* Date:
* Modifier:
* Date:
*/
Note template 2:
/**
* Funname: getfirstspell
* Description: gets the first letter of Chinese characters and pinyin,
* Function call with hundreds of surnames generated
* @ Param: Str the string is a string containing Chinese characters.
* @ Return string: returns the first letter of a Chinese character;
* Uppercase letters are returned;
* Other non-simplified Chinese characters return '0 ';
* @ Author: ghc
* @ Create Date: 2008-07-02
*/

5. Method comments:
Method annotation using /**...... */. For methods for setting (set method) and getting (get method) members, you can leave no comment if the member variables already have descriptions; common member methods require that you describe the functions to be completed, the meanings of parameters, and the returned values. In addition, the creation time of methods must be clearly stated to provide valuable evidence for future maintenance and reading.

6. Internal method comments:
The control structure, what the code has done, why it has done so, and the processing sequence, especially the complicated logic Processing Section, should be given as detailed as possible.

7. global variable comments:
A detailed comment should be provided, including descriptions of functions, value ranges, functions or process access, and precautions for access.

8. Notes on local (intermediate) variables:
The main variable must be annotated. If there is no special meaning, you can leave it unannotated.

9. Real parameters/parameter comments:
Parameter description, and any other constraints or prerequisites.

10. Field/attribute description: Field description and attribute description.

11. constants: constants are usually meaningful and must be defined accordingly.