我的对注释使用的总结

我的对注释使用的总结：（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

Key：注释条件，注释类别，注释快捷键，注释规范（我的经常使用）

背景：模拟操做系统的课程设计的代码量算是我学习编程以来相对较多的，代码量大的同时，方法间的调用十分频繁，调用者也包括了好几个类（这跟项目结构有关系，一开始没有作好分析）。此以前不过重视注释的规范，看了队友的代码才发现，在IDE的帮助下，若是按照规定的注释规则，在使用到方法或者新建对象时，注释的内容能够在鼠标悬浮下显示，能够借注释提示本身定义的某个方法或者类的使用说明，参数说明等，省去回到类或者方法找注释的时间。固然，若是没有按照规则写注释，就只能手动回去找了。在团队合做中，若是使用不符合规范的注释，可能会让队友浪费不少没必要要的时间。

正文：

合理地运用注释是团队开发合做的重要细节，它能提升代码的规范性和可读性，并且在IDE的帮助下，使用符合规则的注释能够方便本身开发时就地查看部分代码注释，一样的也方便了他人阅读代码。

代码注释要求注释形式统一，内容言简意赅，准确明了地表达注释意图。

注释条件（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

一、基本注释（必须加）

(a)    类（接口）的注释

(b)    构造函数的注释

(c)    方法的注释（持久化对象或VO对象的getter、setter方法不需加注释）

(d)    全局变量的注释

(e)    字段/属性的注释

二、特殊必加注释（必须加）

(a)    典型算法必须有注释。

(b)    在代码不明晰处必须有注释。

(c)    在代码修改处加上修改标识的注释。（*合做中使用队友代码尤为注意）

(d)    在循环和逻辑分支组成的代码中加注释。

(e)    为他人提供的接口必须加详细注释。

 

注释格式（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

1.单行(single-line)注释：“//……””/* ... */”

2.块(block)注释：“/*……*/”(块注释通常包含多行文本)

3.文档注释：“/**……*/” （文档注释可在鼠标悬浮时显示）

4. javadoc 注释标签语法

@author   对类的说明 标明开发该类模块的做者

@version   对类的说明 标明该类模块的版本

@see     对类、属性、方法的说明 参考转向，也就是相关主题

@param    对方法的说明 对方法中某参数的说明

@return   对方法的说明 对方法返回值的说明

@exception  对方法的说明 对方法可能抛出的异常进行说明

 

为了能显示文档注释，须要对于不一样的情境使用特定的注释语法，使用相应的注释快捷键能提升效率。

1. 几种注释快捷键（Android Studio)

        a.单行注释//      ctrl+/

        b.单行注释/**/    ctrl+shift+/

        c.块注释          /*+回车

        d.方法注释       /**+回车

2. 几种注释规范：

        a.全局变量

          /** 全局变量注释*/

private int TOTAL;

   

         b.类（接口）注释（新建类时会在类头部自动生成注释模板内容）

/**

 * 类描述

 * Created by ${USER} on ${DATE}

 */

public class Foo {

}

注释模板设置（android studio)：File->Settings->IDE Settings->File and Code Templates -> include(Tab栏） ->选FileHeader

 

c.构造方法或普通方法的注释(在含有参数的方法(包括构造方法)上方 输入/**后回车会对参数进行注释)

public class Foo {

    /**

     * 对构造方法的描述

     */

    public Foo(){

...

    }

        /**

         * 对方法的描述

     * @param a 对参数a的描述

     */

    private void test(int a){

        ...

    }

}

 

对于注释的使用，总结以下：

1. 单行注释用于描述普通变量（10字之内，尽可能不要换行），

        例 private String title;//不能超过120个中文字符

    或者对某行代码进行解释

         %^E%^*&(*&(*)*)(T^%$%^$%   //只对逻辑不容易看懂代码的进行注释

2. 常量注释用/**  常量说明  */

         例：/**  CONSTANT是常量  */

         private int CONSTANT;

3. 通常不对getter 和setter方法注释。

4. 注释的目的是帮助阅读代码。不要为了注释而注释。使用合理的命名方法能够帮助精简注释。