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)
    }

}

注意:常用标签及含义

标签 描述
@author 说明类或接口的作者
@deprecated 说明类、接口或成员已经废弃
@param 说明函数参数
@return 说明返回值
@see 参考另一个主题的链接
@exception 说明函数所抛出的异常类
@throws 同@exception标签
@version 类或接口的版本

如果想生成 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  <源代码目录>
  • 代码注释:就是给阅读源代码的人参考的。代码注释一般是采用单行注释 (//) 和多行注释 (/* ... */)。
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
}

你可能感兴趣的:(Kotlin基础认识 (3)编码规范)