Kotlin基础认识 (3)编码规范

一、命名规范(首推驼峰命名)

• 包名：全小写字母，中间可以由点分隔开。
  com.ak.snails
• 类和接口名：采用大驼峰命名。
  Model
• 文件名：采用大驼峰命名。
  LoginActivity.kt
• 变量名：采用小驼峰命名。
  studentName
• 运行期常量名：采用小驼峰命名。
  studentAge
• 编译期常量名：全大写，如果是由多个单词构成，可以用下划线隔开。
  YEAR 或者 WEEK_OF_MONTH
• 函数名：采用小驼峰命名。
  getName

注意： 驼峰命名-是指混合使用大小写字母来命名。驼峰命名分为小驼峰法和大驼峰法。小驼峰法-第一个单词是全部小写，如 myName 。大驼峰法-每一个单词的首字母都大写，如 SuitRoom 。

二、注释规范

• 文件注释：就是在每一个文件开头添加注释。文件注释通常包括如下信息，版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。

/*
* 版权所有 2019 校园科技发展有限公司
* 描述
*     实现日期基本功能
* 历史版本
*     2019-1-2：   创建  lawrence
*     2019-3-15：  添加 日期格式转换
*/

• 文档注释：就是指注释内容能够生产API帮助文档，称为Kdoc。Kdoc通过一些工具从Kotlin源代码的文档注释中提取信息，并生成HTML文件，即Kdoc文档。文档注释主要对类（或接口）、属性和函数等进行注释。

package cn.ak.kot

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

/**
 * 主程序入口页面，用于展示...
 * 实现首页炫目UI
 * @author lawrence
 */
class MainActivity : AppCompatActivity() {

    /**
     * 构建页面UI，只执行一次
     * @param savedInstanceState 参数
     */
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }

}

注意：常用标签及含义

如果想生成 Kdoc 文档，则需要使用 Dokka (https://github.com/Kotlin/dokka) 工具，Dokka 支持 java 和 kotlin 混合项目生成 Kdoc 文档，Dokka 提供多种使用方式，可以配置到 Gradle、Maven 和 Ant 项目的依赖插件中，直接在项目中生成，也可以直接使用命令行工具生成。如果使用命令行工具生成，则需要从 https://github.com/Kotlin/dokka/releases/download/0.9.10/dokka-fatjar.jar 中下载文件，然后在命令提示行执行如下语句：

java -jar <dokka-fatjar.jar 文件路径> <源代码目录>

• 代码注释：就是给阅读源代码的人参考的。代码注释一般是采用单行注释 (//) 和多行注释 (/* ... */)。

override fun onCreate(savedInstanceState: Bundle?) {
    // 调用父对象的onCreate方法
    super.onCreate(savedInstanceState)
    // 设置页面显示布局
    setContentView(R.layout.activity_main)
}

fun doSomethings(a: Int, b: Int): Int {
    /*
    if (a > b) {
    } else {
    }
    */
}

• 地标注释：就是在代码中加一些标识，便于IDE工具快速定位代码，称为“地标注释”。

IntelliJ IDEA 工具支持如下两种地标注释
* TODO ：说明此处有待处理的任务，或代码没有编写完成。
* FIXME ：说明此处代码是错误的，需要修正。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    // TODO: 初始化组件
}

fun modify(order: String): Int {
    // FIXME: 排序错误
    return 0
}