Swift 注释规范和文档注释

时间:2024-04-10 14:00:35

Swift 注释规范

目录

Swift 注释规范

一、 普通注释

二、 MARK、TODO、FIXME

三、 文档注释

四、 Playground注释


今天,我知道我写是什么,上帝和我知道

明天,我知道这个代码什么意思,

后天,我知道这是我写的代码,

一周后,这TM谁写的代码,此时只有上帝才知道啥意思

论代码注释的重要性。

 

一、 普通注释

普通注释主要为了提示编码者,逻辑注释等作用,一般不会再文档中提示。

1. 单行注释  //

var str = ""
// 修改str变量的值
str = "a new value"

2.多行注释 /*   */

/*
这里是多行注释
多行注释里也可以成对出现
/*
子注释
*/

*/
code

 

二、 MARK、TODO、FIXME

 

MARK:  代码文件结构标记,可以显示文件的大致结构和模块,说明建议使用首字母大写

// MARK: - Properties
// MARK: - Initialization
// MARK: - IBAction Method
// MARK: - XXXDelegate

TODO: 待完成标记, 代表此处有需要完成的功能或者后续开发。

// TODO: - 待完成的功能
// TODO: - Need to finish

FIXME:  检查标记, 通常用于需要检查的地方,比如临时修改变量为固定值方便测试,或者为了走通流程,注释部分代码等,都需要添加标记,方便后期提醒自己,万一忘了。最好上线前全局搜索检查下。

代码文件结构(Ctr + 6 )

Swift 注释规范和文档注释
代码文件结构

三、 文档注释

文档注释用于输出代码文档和阅读方便,规范的文档可以在Quick Help中看到或者Alt + 左键快速查看相关说明。更或者可以输出说明文档给别人使用

文档注释也分为单行和多行,不过根据苹果Swift 开源代码可以看出 基本都使用单行注释

文档注释的对象: 自定义类型、变量、方法等,但是重点还是方法说明

 

Tip: 由于文档注释通常是多行和多标识字段, 所以此时就可以用Xcode Code Snippet 代码段收藏与引用

 

单行注释 ///

类型文档说明

/// 用户信息
struct UserInfo {
    /// 昵称
    var nickname: String
    /// 性别 ture: 男,  false: 女
    var isMale: Bool
}

可惜的是swift 没有发现对属性的行尾注释。

方法文档说明

    /// 文档注释参考 【单行】
    /// - parameter pram: 单参数
    /// - returns : 返回结果是否成功 ture: 成功  false: 失败
    ///
    /// 其他discussion 详细说明  // 【注意】必须隔一行
    func singleLineComment(pram:String) -> Bool {
        print("注释参考")
        return true
    }

多行注释 /**   */

    /**
     文档注释参考 【多行注释】  // 【注意:必须新起一行】
     - parameter p1: The number of Llamas spotted on the trip
     - parameter p2: The number of Llamas spotted on the trip
     - returns: 返回结果字符串数组
     
    其他discussion说明  // 【注意】同样必须隔一行
     */
    func text(p1:String , p2:Bool) -> [String] {
        return [String]()
        
    }

支持 markdown 语法

除了使用关键字比如ruturns 来让文档更好看之外,我们还可以使用markdown丰富说明。单行和多行文档注释都支持markdown,但是这个时候个人建议就使用多行注释

     /**
     # 支持markdown
     # 一级标题
     ## 二级标题也可以的
     注释参考2
     隔一行表示换行d
     
     三个”***"代表一条分割线
     ***
     ## 使用示例
     ```
     let result = testComment2(pram: "参数1", param2: true))
     ```
     
     ****
     - important:这个很重要
     - returns: 有返回值
     - parameter pram: The cubes available for allocation
     - parameter param2: The people that require cubes
    
     */
    func testComment2(pram:String, param2:Bool) -> Bool {
        print("markdown支持")
        return true
    }

Quick Help 显示

Swift 注释规范和文档注释

playground 示例代码: gitee

swift Documentation

四、 Playground注释

苹果官方文档: Xcode Help -- Use playgrounds

Playgound 也支持markdown , 而且还可以做成跳转文档的模式。

比如,官网Sample Code, JSON与模型互转 下载即可