AS巧用IDEA注释，提高协作/开发效率

目录

一、简介&举例

二、基础注释规范

三、提高协作

四、模板

---

一、简介&举例

约定一套规范的注释，有利于组员之间的协作开发，也方便与服务端对接。充足的注释能够组员间、前后端协作效率。减少不必要的方法重复实现。规范的类结构注释还能提升代码可读性。

有利于提升协作效率的注释包括：

1.类结构可读性注释（代码规整）

2.Response Bean类文档外链注释

3.api方法入参注释、文档外链注释

4.类用途注释

4.方法目的、出入参注释等

举例1：

结构化，提升可读性，几百行的代码按需折叠/展开

举例2：

比如处理一个IM事件，如果在register()处写好注释，标注好业务类/方法，从方法注释就可跳转到业务实现，其他组员接手的话，就不需要全局搜索、阅读其他搜索结果，跳跃三四个类文件，才找到对应的业务代码。

举例3：

比如与服务端接口对接，如果在Repository类中对应HttpParam方法注释上，标注文档链接🔗，则后续组员接手时，可以直接点击，查看接口文档入参信息等。同理，在对应的接口Response Bean类上，标注文档链接🔗，则其他组员接手时，可以直接点击查看字段定义的信息。

不仅如此，未来接口有变更字段或者入参，可以【代码】->【接口文档】直通，快速对接，方便他人页方便自己。

二、基础

2.1 常用：

 每个类都要相应的功能描述（包含使用、注意事项、代码示例等等）、作者、时间

/**
 * TODO 类描述
 *
 * @author xxx
 * @date ${YEAR}-${MONTH}-${DAY}
 */

/**
 * $END$
 * @author： $USER$
 * @date： $DATE$
 * @param：
 * @return：
 */

2.2 常用注释标签

2.3 HTML标签

基本所有的HTML标签都支持，便捷性较低，可以通过LiveTemplate解决

三、提高

3.1 结构化注释/代码归纳

先看效果，一个类结构化注释后非常精简

3.1.1 region:

1.适用于仅需要一个结构化注释的场景，一个类文件不建议多次使用。因为后续注释的模块会被归纳为结构子项，【// region】只会匹配类文件的最后一个【// endregion】，中间多余的【//endregion】无效，中间多余的【// region】会被识别为内部子分类

// region 文件播放流程操作
 private fun playVoice() {
        ...
 }
 private fun playPause() {
        ...
 }
 private fun playGoOn() {
        ...
 }

 private fun playStop() {
        ...
 }
// endregion

3.1.2 editor-fold（推荐使用）

1.适用于一个或多个的结构化注释场景，可以再一个类文件中多次使用。

2.缺点是书写✍🏻麻烦，这一点可以利用live template 解决，使用【common+option+j】唤出快捷注释

3.与region不共存

// 
 private fun playVoice() {
        ...
 }
 private fun playPause() {
        ...
 }
 private fun playGoOn() {
        ...
 }
 private fun playStop() {
        ...
 }
// 

3.2 跳转http链接(接口文档、需求文档)

与✍🏻写Markdown一样，[接口文档](https://xxx)

   /**
     * 获取 互动消息 list
     * [接口文档](https://api-gw.admin.internal.taqu.cn/docs/gw-api/gw-api-1dsi59l13oa9o)
     */

3.3 接口类注释自动带到实现类

勾选Copy JavaDoc

3.4 跳转指定类

       /**
         * 在线匹配
         *
         * im 数据类:
         * @see com.xmhaibao.friend.fish.im.bean.FriendFishResultInfoBean
         */

3.5 跳转指定方法

       /**
         * 在线匹配
         *
         * im 数据处理():
         * @see  com.xmhaibao.friend.fish.activity.FriendFishSendingActivity.onEventMainThread
         */

四、附：几个快捷注释模板

1.region ：代码选中common+option+j 快捷注释

// region $END$
$SELECTION$
// endRegion

2.editor-fold：代码选中common+option+j 快捷注释

// 
$SELECTION$
// 

xml 使用：

$SELECTION$ 

3.外链：

[接口文档]($END$)

[需求文档]($END$)