<Android> .kt文件注释规范

964 阅读2分钟

项目中做好必要的注释~

类注释

image-20220210175028132.png 如图所示,步骤为:Settings -> Live Templates -> 右侧加号 ,Template Group ,创建‘user’分组 -> 右侧加号 ,Live Template ,创建‘cc’快捷方式 -> 填写注释模板
这里分组的名称、快捷键的名称都可以按自己的习惯命名;

/**
 * $desc$
 *
 * @author $author$
 * 
 * create on $date$
 */

这里,被$$修饰之后,可以通过点击Edit variables,配置相应的表达式。如图所示:

image-20220210175109071.png

按上述配置后,快捷键cc后,呈现为:

/**
 * 
 *
 * @author curry
 *
 * create on 2022/2/10
 */

这里@author currycreate on之间,空了一行是为了更好的呈现(如下图),否则会堆积到一行。 image.png

成员变量或常量

建议采用:

/**
  *
  */

方法体注释

.kt文件中,在带有入参的方法体上键入/**回车后,仅会生成

/**
  *
  */

这样的空白注释;而.java文件按上述操作后,是会生成带有@param的注释;

因此为了更方便的快速注释,可以在androidstudio中添加插件BugKotlinDocumentKotlin Doc Generator。Kotlin Doc Generator相较于前者功能更多一点,其中之一是会把方法名按照英文单词拆分直接显示出来。

/**
 * Login
 *
 * @param username
 * @param password
 * @return
 */
fun login(username: String, password: String): Result<LoggedInUser> {
    ...
    return result
}

方法内注释

  • 仅一行注释,建议采用//
  • 多行注释,建议采用/* */

其他注释语法(部分总结)

类似于markdown语法,当需要编写详细注释,可参考如下:

/**
 * 注释示例类
 *
 * [com.curry.interaction2] 这里可以指向项目中的任意类,ctrl+左键可直接进入查看
 *
 * See [Android](https://developer.android.google.cn/)
 *
 * ```
 * //代码块
 * interface HiltInterface {
 *      fun test()
 * }
 * ```
 * `代码`
 *  # 测试1
 *  ## 测试2
 *  ### 测试3
 *
 * * 1
 * * 2
 *      * 2.1(按两次tab键)
 * @author curry
 *
 * create on 2022/1/28
 * @since 版本1.0.0
 * @see com.curry.interaction2
 * //@since较少用到通常后面输入版本
 * //@see后可以任意输入,但通常是指向另一个类
 */

image.png