2016 Android注释技巧 Android Studio

不懂的就要学，这就是成长；一些东西可能很偏，但是不代表可以放弃。

掌握20%的技术可以让你得心应手的解决80%的问题，但是用剩余80%的只是去解决那20%的问题就决定了你的高度！这就是为什么你感觉大家水平差不多，但是人家就是比你强的原因。因为都可以解决的问题不值钱，我能解决而你不能的问题才值钱。

注释是每个代码当中都要使用到的帮助信息，而且专业的注释也可以大大的提高我们代码的可读质量。注释是对一个方法或者类的解释，那么读注释就是为了理解你设计的方法和类有什么作用。

这里需要区别注释和注解的区别，注释是对一个类方法参数的一个解释，而注解是一种编程的辅助手段，当然也有一定的注释功能。

首先教大家一个让项目看起来很高端的东西，当然本来这个在项目中也是应该存在的，但是大多数的时候太苍白了！

那么这个就是配置注释，在每个新建的类中的header 部分都会自动添加一些必要的基础注释。

让我们来看下操作步骤

准备阶段，点击左上角File 打开Settings
1.在输入框里输入 file and code
2.在列表里面选择File and Code Templates
3.选择右侧的Includes
4.选择 File Header
5.根据自己平时的项目需求对右侧的Header内容进行编辑。

这里总结了一些比较基本的需求

/**
 * 项目名称：${PROJECT_NAME}
 * 类描述：
 * 创建人：${USER}   
 * 创建时间：${DATE} ${TIME} 
 * 修改人：${USER}  
 * 修改时间：${DATE} ${TIME}  
 * 修改备注：  
 * @version
 */

注意：上面的英文在 studio必须是大写的

再来看一个快速生成方法参数的注释
首先设置快捷键一般在android studio 里面可能没有设置或者与某些快捷键存在冲突，所以不好使。
那么我们的第一步工作就是设置快捷键以更方便的设置。

准备工作还是从setting 开始
1.在左侧输入栏输入查找keymap
2.在右侧的输入栏输入fix doc comment
3.然后双击 fix doc comment

4.在First Stroke 里面设置一个你喜欢的快捷键，注意看看有没有冲突！
5.当conflicts 里面显示No conflicts 的时候就可以了 这个代表没有冲突

然后在我们写一个方法时候在方法内部使用我们设置的快捷键就会自动为我们添加一些注释
如下：

 /**
     * @param x
     * @param y
     */
    private void testClass(int x,int y)
    {
        //上面的参数注释 是我们在方法内部 使用快捷键生成的。
    }

然后进入今天的正题

首先我们先看一各种注释的字段含义

（空）在所有标签上面写的文字将成为描述该函数的关键性文字
@author 作者信息
@param 参数信息
@return 返回信息
@exception 异常信息
@throws 抛出异常信息 （@exception 和 @throws 经测试效果是一样的）
@category 分类信息
@since 自哪个版本开始
@see 有的函数需要借助其他类或者函数或者属性，就用该标签标识。
@see #本类函数名/属性名 可以查看其他函数或属性
@see 包名.类名 可以查看其他类
@Description

@deprecated 表示该函数不建议使用了，在这个标签里写上为什么不建议使用以及提供替换该方法的新方法。

加上这个标签后，注释显示里不会提示，但是函数名会被画一道删除线

引用到别的参数或者类或者函数。可以这么做：用{@link #函数名/属性名}来链接本类属性/函数，用{@link 包名.类名}来链接其他类

当希望注释换行时，可以在新一行注释前加上

（如果不加，就算换行了，鼠标放在函数上显示的也是没有换行，类似html）

有了注释的好处就是当别人使用这个类的时候 把，光标移上去就可以查看该类的一些基本介绍

@see 有的函数需要借助其他类或者函数或者属性，就用该标签标识。
@see #本类函数名/属性名 可以查看其他函数或属性
@see 包名.类名 可以查看其他类

@deprecated 表示该函数不建议使用了，在这个标签里写上为什么不建议使用以及提供替换该方法的新方法。加上这个标签后，注释显示里不会提示，但是函数名会被画一道删除线

另外，在文档注释里面，比如@param 的解释中，有时候我们需要引用到别的参数或者类或者函数。比如，现在在Person类里面定义两个整型常量，标识男女，在setSex()函数中，我想提示使用者设置我已经给定的两个常量，可以这么做：用{@link #函数名/属性名}来链接本类属性/函数，用{@link 包名.类名}来链接其他类（是不是想到了@see?）

那么@see和@link的区别就是
第一位置不一样
@see是直接在方法或者类的开始的地方进行声明其使用了什么类或者方法 而@link是在params 里面声明的。

第二个写法不一样
@see 直接加类名 #方法
而@link是在params或者是注释性文本中使用需要添加{}
即｛@link className#methodName｝
最后说一个最主要的就是如何查看，写了注释看不了可就白写了。
所以这里在最后补充一个如何查看注释的方法。
（Android studio环境）把光标移动到你要看的方法或者类上，然后使用ctrl+Q快捷键查看，要是发现没有呼出注释面板，那么回到settting 中查看quick doc

如果有冲突，那么自己解决。和之前修改快捷键的方法一样。