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 ）

编译器提示

有些提示，我们希望在编译期间就看到定制提示或错误，我们就可以使用如下标记：

#error：编译器编译到这里就会停止，并展示携带的 message

#warning: 编译器编译到这里就会提示 message 信息

示例：

#warning("Needs to be refactored")
// some dodgy code here#if !canImport(UIKit)#error("This framework requires UIKit!")
#endif

#error使用情况示例：SDK API key, 代码中必填信息提示，标记当前完成任务在哪里（以便下次接着开发）等情况。

原理解释参考diagnostics-warning-error，apple开源提案描述

文档注释

单行注释快捷键：⌘⌥/ 【 CMD + Alt + / 】

文档注释用于输出代码文档和阅读方便，规范的文档可以在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 显示

playground 示例代码： gitee

swift Documentation

Playground注释

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

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

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

代码约束规范

对于平时的代码规范，Swift 语言可以使用 SwiftLint 工具来约束。对代码习惯进行强约束，不符合的将提示警告或错误。

具体集成步骤参考 SwiftLint 官方文档

下面是 Cocoapod 检查脚本优化版本（只检查变动文件，避免全局检查，省略编译时间）

# Run SwiftLint
START_DATE=$(date +"%s")SWIFT_LINT="${PODS_ROOT}/SwiftLint/swiftlint"# Run SwiftLint for given filename
run_swiftlint() {local filename="${1}"if [[ "${filename##*.}" == "swift" ]]; then# ${SWIFT_LINT} autocorrect --path "${filename}"${SWIFT_LINT} lint --path "${filename}"fi
}if [[ -e "${SWIFT_LINT}" ]]; thenecho "SwiftLint version: $(${SWIFT_LINT} version)"# Run for both staged and unstaged filesgit diff --name-only | while read filename; do run_swiftlint "${filename}"; donegit diff --cached --name-only | while read filename; do run_swiftlint "${filename}"; done
elseecho "${SWIFT_LINT} is not installed."exit 0
fiEND_DATE=$(date +"%s")DIFF=$(($END_DATE - $START_DATE))
echo "SwiftLint took $(($DIFF / 60)) minutes and $(($DIFF % 60)) seconds to complete."