《Kotlin从小白到大牛》第5章：Kotlin编码规范

第5章 Kotlin编码规范

俗话说：“没有规矩不成方圆”。编程工作往往都是一个团队协同进行，因而一致的编码规范非常有必要，这样写成的代码便于团队中的其他人员阅读，也便于编写者自己以后阅读。
# 5.1 命名规范
程序代码中到处都是标识符，因此取一个一致并且符合规范的名字非常重要。
命名方法很多，但是比较有名的且被广泛接受的命名法包括下面两种。
o 匈牙利命名，一般只是命名变量，原则是：变量名
= 类型前缀 + 描述，如bFoo表示布尔类型变量，pFoo表示指针类型变量。匈牙利命名还是有一定争议的，在Kotlin编码规范中基本不被采用。
o 驼峰命名（Camel-Case），又称“骆驼命名法”，是指混合使用大小写字母来命名。驼峰命名又分为小驼峰法和大驼峰法。小驼峰法就是第一个单词是全部小写，后面的单词首字母大写，如myRoomCount；大驼峰法是第一个单词的首字母也大写，如ClassRoom。
除了包和编译期常量（const val声明的常量）外，Kotlin编码规范命名方法采用驼峰法，下面分类说明一下。
o 包名：全小写字母，中间可以由点分隔开。作为命名空间，包名应该具有唯一性，推荐采用公司或组织域名的倒置，如com.apple.quicktime.v2。但Kotlin和Java核心库包名不采用域名的倒置命名，如kotlin.collections和java.awt.event。
o 类和接口名：采用大驼峰法，如SplitViewController。
o 文件名：采用大驼峰法，如BlockOperation.kt。
o 变量名：采用小驼峰法，如studentNumber。
o运行期常量名（只读变量）：采用小驼峰法，如yearLength。
o 编译期常量名：全大写，如果是由多个单词构成，可以用下划线隔开，如YEAR和WEEK_OF_MONTH。
o 函数名：采用小驼峰法，如balanceAccount、isButtonPressed等。

命名规范示例如下：
package com.a51work6

import java.lang.IllegalArgumentException

class Date : java.util.Date() {

var size: Int = 0

public override fun toString():String {
    val year = super.getYear() + 1900
    val month = super.getMonth() + 1 
    val day = super.getDate()
    //...
    return "$year-$month-$day"
}

companion object {

    private val DEFAULT_CAPACITY = 10
    
    fun valueOf(s: String): Date? {
    
        val yearLength = 4
        val monthLength = 2
        
        val firstDash: Int
        val secondDash: Int
        
        //...
        
        return null ?: throw IllegalArgumentException()
    }
}

}

5.2 注释规范

Kotlin中注释的语法有三种：单行注释（//）、多行注释（/…/）和文档注释（/**…*/）。本节介绍如何规范使用这些注释。

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

• 版权所有 2015 北京智捷东方科技有限公司
• 许可信息查看LICENSE.txt文件
• 描述:
• 实现日期基本功能
• 历史版本:
• 2015-7-22: 创建 关东升
• 2015-8-20: 添加socket库
• 2015-8-22: 添加math库
  */
  上述注释只是提供了版权信息、文件内容和历史版本信息等，文件注释要根据本身的实际情况包括内容。

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

文档注释示例：
package com.a51work6

import java.lang.IllegalArgumentException

/**

• 自定义的日期类，具有日期基本功能，继承java.util.Date

• 实现日期对象和字符串之间的转换

• @author 关东升
  /
  class Date : java.util.Date() {
  /*

  • 容量
    */
    var size: Int =0

  /**

  • 将日期转换为yyyy-mm-dd格式的字符串
  • @return<