Java annotation specification for java programming specifications

If there is no comment on the Code, it is a bunch of messy letters for readers. To improve the readability and maintainability of the code, you must make necessary comments on the Code. Here, I have compiled the java comment specifications.

(1) Skills

1: Comment the current row shortcut: ctrl +/

2:/**/select the code to be annotated ctrl + Shift +/

(2) Where can I add comments?

1: Each source file should start with a set of comments, including the author and time of the Code;

2: When the code is long and contains multiple layers of nesting, curly braces will be large and messy. To facilitate reading, you should add comments at the end of some paragraphs, specify the starting point of the closed curly braces;

3: each method must be annotated. when commenting on methods, it is best to place the annotation above the code. when commenting on the variable declaration, it is best to put the annotation at the end of the line, however, the end comments of multiple rows should be aligned;

4: comments must be added to typical algorithms. comments must be added to codes with bugs or unclear values. Comments of modified codes must be added to the comments of modified symbols.

(3) What principles should annotations follow?

1: use indentation and blank lines to separate comments from codes. The code and comments can be easily identified without color prompts;

2: Separate the comment content and the comment separator with a space to facilitate searching for comments;

3: Try not to use/**/for multi-line comments. Instead, use multiple "//" to avoid searching for paired /**/

(4) classification of annotation Methods

1: single line comment -----//

Comment on individual lines:

When a single line is required for a comment, use "//" and leave a blank line before the comment. The indentation should be consistent with the following code. When a row cannot be placed, use multiple rows. In this case, use/**/for comments.

End comment:

Add comments at the end of the line of the code line. Generally, eight cells are left blank and all comments must be aligned.

2: block comment ---/* content */

Comments on several rows, which are usually placed before the method, and describes the functions and meanings of the method and data structure.

/*

* Comment content

*/

3: document comments

Comments on several lines will form an HTML code report. The comments must be written before the class, member variables, member methods, and constructor methods, for example, the following is a comment generated after the servlet is created.

/** * 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();         }

4: Class Annotation

In myEclipse, you can use the shortcut key Alt + Shift + J to generate, you can set the annotation content through Eclipse-> Window-> Preferences-> Java-> Code Style-> Code Templates-> Comments-> Types-> Edt

The format is as follows:

/** * @author ASWH ** @Time 2014-3-30-17:33:01   */

Class English comment Template

/*** CopyRright (c) 2014-xxxx:
 <暗伤无痕>
  
* Project:
  <项目工程名>
   
* Module ID: <(Module) class number. You can reference the class number in the system design> * Comments:
   <对此类的描述，可以引用系统设计中的描述>
    
* JDK version used:
    
     
* Namespace:
     <命名空间>
      
* Author:
      <作者中文名或拼音缩写>
        * Create Date:
       <创建日期，格式:yyyy-mm-dd>
         * Modified:
        <修改人中文名或拼音缩写>
          * Modified Date:
         <修改日期，格式:yyyy-mm-dd>
           * Why & What is modified
          <修改原因描述>
            * Version:
           <版本号>
             */
           
          
         
        
       
      
     
    
   
  
 

Chinese template

/*** File name: * CopyRright (c) 2014-xxxx: * File No.: * Creator: * Date: * revised by: * Date: * Description: * version number :*/

7. constructor comments

/*** Constructor description ** @ param name **/

8: Method comment

/*** Generate random number * @ param numble random number upper limit * @ return * @ exception (if the method has an exception, add) * @ author ASWH * @ Time2014-3-30 17:35:29 */

9: global variable comment

   /** The count is the number of charactersin the String. */   private int count;

It is necessary to describe the functions and methods of variables.

10: Common variables or constants

// Attributes

Appendix: javadoc parameter description:

@ See the hyperlink "see xx entries" in the generated document. You can add "Class Name", "complete Class Name", and "complete class name # method ". It can be used to annotate classes, methods, and variables.
@ Param parameter description. Can be used for: Method annotation.
Description of the return value of @ return. Can be used for: Method annotation.
@ Exception: exception description. Can be used for: Method annotation.
@ Version. Can be used for: Class annotation.
@ Author name. Can be used for: Class annotation.

@ Deprecated: This class or method is not recommended, causing a warning that this class or method is not recommended.

@ Note: The annotation is exposed to the source code reader's documents.

@ Remark: comments and documents exposed to client programmers

@ Since indicates that this function has been available since that version.

@ See indicates cross-reference