Java Annotation Specification

In the process of software development always emphasize the specification of annotations, but not a specific standard to explain, usually in the code to write a simple description of a few sentences, not as a code comment check the standard and basis, do anything to have a basis:), now I have a "Java Annotation specification", The content comes from the network, the books and the actual accumulation of themselves.
Java Annotation Specification

Version/Status Author version date
1.0ghc2008-07-02

I. BACKGROUND
1, when we first contact a piece of code, but is required in a very short period of time to effectively analyze the code, what kind of information do we need to comment?
2, how to avoid our comments lengthy and messy?
3, in the cooperative development and maintenance of many people today, we need what kind of comments to ensure high quality, high-handed development and maintenance work?
Second, the significance
The annotation in the program is an important means of communication between the programmer and the program reader. Application Note specifications are particularly important for the software itself and for software developers. And the concept of turning annotations into code has been proposed in popular agile development ideas. A good annotation specification can reduce the maintenance cost of a software as much as possible, and there is virtually no software that is maintained by the initial developer throughout its lifecycle. A good annotation specification can improve the readability of the software, allowing developers to understand the new code as quickly and thoroughly as possible. Good annotation specification can maximize the cooperation efficiency of team development. Long-term normative coding can also allow developers to develop good coding habits, and even exercise a more rigorous thinking ability.
Iii. Principles of annotations
1. Unified annotation Form
Throughout your application, you construct annotations using styles that have consistent punctuation and structure. If you find that their annotation specifications differ from this document in other project groups, write the code according to their specifications, and do not attempt to introduce new specifications into the established canonical system.
2, The Concise annotation
The content should be simple, clear, meaning accurate, prevent the ambiguity of annotations, wrong comments not only useless but harmful.
3. Consistency of annotations
Write comments before you write your code or write your code, because you probably won't have time to do that later. In addition, if you have the opportunity to review the code you've written, it might not be obvious in six weeks after what seems obvious today. Typically descriptive comments are created prior to code creation, and explanatory comments are created during development, and prompt comments are created after the code is completed. Modify the code while modifying the corresponding comment to ensure that the code is synchronized with the annotation.
4, the location of the note
Ensure that the annotation is adjacent to the code it describes, i.e. the nearest principle of the annotation. Comments on the code should be placed on the next or right position above it, not below. Avoid adding comments at the end of a line of code, and end-of-line comments make your code harder to read. However, the end-of-line comment is appropriate when annotating variable declarations, in which case all end-of-line comments are aligned.
5, the number of comments
Annotations are necessary, but should not be too much, in the actual code specification, the request for comments accounted for the proportion of the program code of about 20%. Comments are "hints" to the code, not documents, and the notes in the program are not distracting, and the notes are too many to dazzle, with fewer notes. Do not write comments passively for writing comments.
6. Delete useless annotations
Before code delivery or deployment is released, temporary or extraneous comments must be deleted to avoid confusion in future maintenance work.
7. Complex annotations
If you need to interpret complex code with comments, check this code to determine if it should be overridden. Try not to comment on the hard-to-understand code, but rewrite it. While you should not generally sacrifice performance to make your code simpler and easier to use, you must maintain a balance between performance and maintainability.
8. Extra Notes
High-level annotations that describe the relationship between the program's functions and the components of the program are most useful, and the low-level annotations that work on a row-by-line interpreter are not conducive to reading, writing, and modifying, and are not necessary and difficult to maintain. Avoid using annotations for each line of code. If the code is clear and straightforward, do not annotate it, and avoid unnecessary or inappropriate annotations.
9, must add the note
A typical algorithm must have comments. There must be a comment in the code that is not clear or not portable. Add a comment that modifies the identity at the point of code modification. Add comments to the code that consists of loops and logical branches. To prevent problems from recurring, use comments on code for bug fixes and workarounds, especially in a team environment.
10. Comments are ignored when compiling code and are not compiled into the final executable, so comments are not
Increases the size of the executable file.
Iv. java Annotation Tips
1, empty lines and white space characters are also a special comment. Use indents and blank lines to make code and annotations easy to area
and coordinate the aesthetics.
2, the contemporary code is relatively long, especially when there are multiple nesting, in order to make the level clear, should be in some paragraphs of the
End Fill (note the starting point of the closure after the closing curly brace), the comment cannot
Write long, as long as you can indicate which control statement is the end of the control range, so easy to read.
3. Separate the comment from the comment delimiter with a space, and when viewing the comment without a color hint,
Doing so makes annotations obvious and easy to find.
4. Do not allow to surround the block annotation with the outer frame. This may look beautiful, but it is difficult to maintain.
5, each line of comments (along with the code) not more than 120 words (1024x768), preferably not more than 80
Word (800x600).
6. Java Editor (IDE) Comment shortcut. ctrl+/comments The current line, and then cancels the comment.
7, for multiple lines of code comments, try not to use "/*......*/", and the use of multiple lines "//" comments,
This is a hassle, but do not look for paired "/*......*/" when doing masking debugging.
8. Note As a code toggle switch for temporary testing to mask some code.
Example one:
//*/
CodeSegement1;
//*/
Change the first line to be:
/*/
CodeSegement1;
//*/
Example two:
----------------------The first paragraph is valid, the second paragraph is commented
//*/
CodeSegement1;
/*/
CodeSegement2;
//*/
Just delete the first line/it can become:
----------------------The first paragraph is commented, the second paragraph is valid
/*/
CodeSegement1;
/*/
CodeSegement2;
//*/
V. Java annotation methods and formats
1, single-line (single-line)-Short Note://...
Individual line comments: A single line of comments in the code, preferably with a blank line before the comment, and with the same indentation level as the code behind it. If a single line cannot be completed, the block comment should be used.
Comment Format:/* Comment content */

Costume Comment: Comment at the beginning of the line of code. Primarily to make the line code meaningless.
Comment Format://comment Content

End of line Comment: End (trailing)-a very short comment that is commented at the end of the line of code. Typically with a line of code after 8 (at least 4) of the grid, all comments must be aligned.
Note format: Code + 8 (at least 4) spaces +//comment content
2, Block--block Comment:/*......*/
Comment on several lines, usually to provide a description of the meaning and purpose of a file, method, data structure, and so on, or an algorithm. Usually located in the front of a file or a method, play the role of guidance, you can also be placed in the appropriate position as needed. This domain comment does not appear in the HTML report. Note formats are usually written as:
/*
* Comment Content
*/
3. Document Comment:/**......*/
Comment on several lines and write to the Javadoc document. Each document comment is placed in the comment delimiter
/**......*/, the annotation document will be used to generate HTML-formatted code reports, so the comment text
The document must be written before the class, domain, constructor, method, and field definition. A note document consists of two parts-a description, a block tag. Note The format of the document is as follows:
/**
* The Doget method of the servlet.
* This method was called when a form have 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);
}
The first two behaviors are described, and after the description is finished, the @ sign begins with the block tag annotation. More about the documentation note
For more information on Javadoc, see Javadoc's homepage: http://java.sun.com/javadoc/index.html
4. Javadoc annotation Tag syntax
@author description of the class indicates the author of the development of such a module
@version the description of the class indicates the version of the class module
@see a reference to the description of classes, properties, methods, and related topics
Description of a parameter in a method @param description of the method
Description of the method return value @return The description of the method
@exception the description of the method, describe the exceptions that the method might throw
VI. implementation of Java annotations
1. source file comments
Source file comments Using/** ... * *, the header of each source file must have the necessary annotation information, including: file name, document number, version number, author, time of creation, document description including the history of this document modification records. Chinese annotation Template:
/**
FileName
* Copyrright (c) 2008-xxxx:
* File Number:
* Create Person:
Date
* Modify Person:
Date
Description
* Version number:
*/

2. Class (module) Notes:
Class (module) comments using/** ... * *, in each class (module) of the head to have the necessary annotation information, including: Project Name, Class (module) number, namespace, class can run JDK version, version number, author, creation time, Class (module) function description (such as function, main algorithm, The relationship between the internal parts, the relationship between the class and its class, and, if necessary, some special hardware and software requirements, such as the description of the main function or process list and this class (module) history modification records.
English annotation Template:
/**
* Copyrright (c) 2008-xxxx: < Outlook software Forsoft >
* Project: < project name >
* Module ID: < (module) class number, which can refer to the class number in the system design >
* Comments: < Description of this class, you can refer to the description in the system design >
* JDK version used: <JDK1.6>
* Namespace: < namespaces >
* Author: < author Chinese name or pinyin abbreviation >
* Create Date: < created dates, format:yyyy-mm-dd>
* Modified by: < edit Chinese name or pinyin abbreviation >
* Modified Date: < date Modified, format:yyyy-mm-dd>
* Why & What is modified < modification reason Description >
* Version: < edition number >
*/
If the module is only partially modified with a small amount of code, the following comments must be added to each modification:
Rewriter
Rewrite date:< Date Modified: Format yyyy-mm-dd> Start1:
/* Original Code content */
END1:
Comment out the contents of the original code, and then add the new code using the following comments:
Added by
Add date:< date, format:yyyy-mm-dd> Start2:
End2:
If the module input or output parameter or the functional structure has a large modification, each modification must add the following
Comments:
Log id:<log number, starting from 1 Add >
depiction:< description of this modification >
Writer: Chinese name of the person who modified
Rewrite date:< Module Modified date, format:yyyy-mm-dd>

2. Interface notes:
interface annotations Using/** ... * *, on the basis of satisfying class annotations, the interface annotations should contain the purpose of describing the interface, how it should be used, and how it should not be used, and the block mark part must be annotated with the author and version. The corresponding implementation class can be annotated without the explicit interface annotations.

3. Constructor Comment:
The constructor comment takes the/** ... * *, the description section indicates the function of the constructor, not necessarily the block tag part.
Comment Template one:
/**
* Default constructor
*/
Comment Template two:
/**
* Description: With parametric constructors,
* Initialize schema name, name and data source type
* @param schema: schema name
* @param name:
* @param type: Data Source types
*/

4. Function Comment:
The function note takes the/** ... * *, in front of each function or process to have the necessary annotation information, including: function or procedure name, function description, input, output and return value description, call relationship and call relationship description, etc. The version number (@version) may not appear in the function comment.
Comment Template one:
/**
* Function Name:
* Function Description:
* Input parameters: < by parameter definition order >
* < @param trailing space followed by variable name of parameter
* (not a type), followed by a description of the argument to the space. >
*
* Return Value:-type < description >
* < Returns a constructor or function that is empty (void),
* @return can be omitted; If the return value is an input parameter, you must * use the same descriptive information as the @param of the input parameter; If necessary, specify the return value written in the special condition. >
* Exception:< in alphabetical order by exception name >
* Create Person:
Date
* Modify Person:
Date
*/
Comment Template two:
/**
* Funname:getfirstspell
* Description: Get the first letter of Chinese pinyin string,
* Generated surnames function call
* @param: STR is a string containing Chinese characters
* @return String: Chinese characters return pinyin first letter string;
* English letter returns the corresponding uppercase letter;
* Other non-Simplified Chinese characters returned ' 0 ';
* @Author: GHC
* @Create date:2008-07-02
*/

5. Method Notes:
The method note uses the/** ... * *, for a method that sets (set method) and gets (get method) member, in case the member variable already has the explanation, can not annotate, the ordinary member method asks to describe what function is completed, what the parameter meaning is and what value is returned, and the time of creation of the method must be annotated clearly, Provide valuable clues to future maintenance and reading.

6, the method internal comment:
Control the structure, what the code does, and why it is done, the processing order, and especially the complex logical processing part, to give as much detail as possible.

7. Global variable Comment:
For a more detailed comment, include a description of its functionality, range of values, which functions or procedures are accessed, and the considerations for access.

8. Local (Intermediate) variable Comment:
The main variable must be annotated, without any special meaning.

9. Argument/Parameter Comment:
The meaning of the parameter, and any other constraints or prerequisites.

10. Field/Attribute Comment: Field description, property description.

11, constants: constants usually have a certain practical significance, to define the corresponding description.

Java Annotation Specification