今天,我知道我写是什么,上帝和我知道
明天,我知道这个代码什么意思,
后天,我知道这是我写的代码,
一周后,这TM谁写的代码,此时只有上帝才知道啥意思
论代码注释的重要性。
普通注释
普通注释主要为了提示编码和阅读者,逻辑注释等作用,一般不会在文档中提示。
单行注释 //
// 定义一个空字符串
var str = ""
// 修改str变量的值
str = "a new value"
多行注释 /* */
/*
这里是多行注释
多行注释里也可以成对出现
/*
子注释
*/
*/
结构性或者功能提示
MARK
MARK: 代码文件结构标记,可以显示文件的大致结构和模块,说明建议使用首字母大写
// MARK: - Properties
// MARK: - Initialization
// MARK: - IBAction Method
// MARK: - XXXDelegate
TODO
TODO: 待完成标记, 代表此处有需要完成的功能或者后续开发。
// TODO: - 待完成的功能
// TODO: - Need to finish
FIXME
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 代码段收藏与引用
单行注释 ///
文档说明,Xcode会根据注释产生相应文档和提示。
/// 用户信息
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 显示
Document Reference
支持文档跳转
Xcode 14后,支持制作自己项目的文档,我们可以在注释中通过使用``快速跳转,支持各种定义,方法
struct Student {
var name: String
}
struct Class {
var students: [Student] = []
/// 添加一个学生
/// - Parameter student: 学生``Student``
mutating func insertStudent(_ student:Student) {
students.append(student)
}
}
在 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}" ]]; then
echo "SwiftLint version: $(${SWIFT_LINT} version)"
# Run for both staged and unstaged files
git diff --name-only | while read filename; do run_swiftlint "${filename}"; done
git diff --cached --name-only | while read filename; do run_swiftlint "${filename}"; done
else
echo "${SWIFT_LINT} is not installed."
exit 0
fi
END_DATE=$(date +"%s")
DIFF=$(($END_DATE - $START_DATE))
echo "SwiftLint took $(($DIFF / 60)) minutes and $(($DIFF % 60)) seconds to complete."