Comments for Java

Recently in the Java project began to focus on and attention to some Java specifications, just to make yourself and others easier to understand the code and reuse of their own writing.

　　An important principle is: ask yourself, if you have never seen this code, you need to quickly know what the code is doing, what information do you need?

Single-line comments and block comments (multiple lines) These books and learning time will know not here to write, mainly write a document comments, in fact, this can refer to the Java API documentation, Java API documentation is also written in accordance with a certain specification comments!

Javadoc annotation Tag Syntax

@author the 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 the       reference to the class, attribute, and method refer to the turn, that is, related topics @param     the method Description of a parameter in the method @return to the description of the method to the method     return value of the description @exception the description of the method of the method may throw an exception to explain

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:
　　

/** * File name:   * Copyrright (c) 2016-xxxx: * File Number: * Creator: * Date: * Modified by: * Date: * Description: * Version number: * * 

2. Class (module) Comments:
Class ( module) comments using/** ... * *, in the head of each class to have the necessary annotation information, including: project name; class number; namespace; The JDK version that the class can run, the version number; author; creation time; class function description (such as function, main algorithm, relationship between internal parts, The relationship between the class and its class, if necessary, some such as special hardware and software requirements, such as the description of the main function or process list and this kind of historical modification records.
English annotation Template:

   /** * Copyrright (c) 2016-xxxx:   < Outlook software Forsoft >                          * Project:  < Project project name >                                         * Module id:
    
     < (module) class number, you can refer to the class number in the system design >      * Comments:  < Description of this class, you can refer to the description in system design >                                          * JDK version used:   < Jdk1.6>                             * Namespace:   < namespace >                             * Author: < author Chinese name or pinyin abbreviation > * Create date                : < creation date, Format:yyyy-mm-dd> * Modified by:  < change person's Chinese name or pinyin abbreviation >                                        * Modified Date:  < Modified date, format: yyyy-mm-dd>
        * Why & Modified  < Modify reason Description > * version   :  < release number >                      　　　　　　
    * /             

3. 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.

4. 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 constructor, *@param@param@param  t ype: Data Source Type  * /    

5. Function Notes:
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:     < According to the parameter definition order > * < @param followed by a space after the argument name * (not the type), followed by a description of the parameter.　　　　> * return value:  @return@param The same descriptive information, and when necessary, specify the return value of the special condition write. * Exception:< in alphabetical order of exception name > * Creator: * Date: * Modified by: * Date: */           

Comment Template two:

         /**   * funname:  getfirstspell  * Description:   Get the first letter of Chinese pinyin string  ,　　　　　@param: The Str is a  string that contains Chinese characters @return string : Chinese characters return pinyin initials;  * @Author:  Sky  * @c reate date:2016-07-21  　 * /   

6. 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.

Method Internal comments: Control structure, what the code does and why, the processing order, especially the complex logic processing part, to give as much detail as possible.

7. Other Notes

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.
Local (Intermediate) variable Comment:
The main variable must be annotated, without any special meaning.
Argument/Parameter Comment:
The meaning of the parameter, and any other constraints or prerequisites.
Field/Attribute Comment:

Field Description, property description.
Constant:

Constants often have some practical significance, and you define the corresponding descriptions.

Comments for Java