• 注释规约


    代码注释说明

    良好的注释不仅可以帮助自己和其他开发者理解代码结构,也可以用在项目编译时生成javadoc,避免重复工作。
    现代IDE可以通过模板的方式自动生成一些格式化的注释,在此我们提供模板的规范。请不要使用非Javadoc标准的注解,如@date。

    类注释

     /**
      * <p>
      * description
      * </p>
      * 
      * @author xxxx@hand-china.com 2018/06/07 13:48
      */
     public class Demo {
    
     }
    

    方法注释

    /**
     * <p>description<p/>
     *
     * @param name meaning
     * @param list meaning
     * @return the return
     * @throws RuntimeException exception description
     */
    String test(String name, List<String> list) throws RuntimeException;
    
    public void test(){
        // 单行注释
        String single = "";
    
        /*
        * 多行注释
        * 多行注释
        */
        String multi = "";
    }
    
    // description
    private void test3 () {
        // ...
    
        /* ... */
    }
    

    字段注释

    /**
     * 静态字段描述
     */
    public static final String STATIC_FIELD = "DEMO";
    
    /**
     * 姓名
     */
    private String name;
    

    特殊注释标记

    public void test3 () {
        // TODO 待完成 [author, time]
    
        // FIXME 待修复 [author, time]
    }
    

    分隔符

    //
    // 说明
    // ------------------------------------------------------------------------------
    
    //===============================================================================
    //  说明
    //===============================================================================
    

    其它

    Eclipse 注释模板

    Eclipse开发时可以使用导入功能直接导入Eclipse模板Window -> Preferences -> Java -> Code Style -> Code Templates -> Import

    IntelliJ IDEA 注释模板

    IntelliJ IDEA 只能通过设置注释模板来实现,请先导入IDEA注释模板File -> Import Settings

    该模板内置了几种常用注释:

    JavaDoc