一直以来我只是用双斜杠进行注释,但是我发现Xocode官方会有专门的注释,按option点击就会出现相关的注释内容。研究了一下发现Swift的注释非常强大。

前言

写代码也有一段时间了,代码中注释也是写了不老少,但在和同事一起开发的时候才发现了问题,大家注释的样子各成一体,没有能写出苹果官方注释的样子。大概就是注释的语法上出了问题,于是自己就主动学习了下 Swift代码的注释语法格式,记录下自己学到的东西。

注释语法

单行注释

1
// 单行注释
  • 单行注释主要出现在. swfit 文件的顶部,记录代码文件的一些信息。
  • 另外也出现在代码中,用于记录对于单行代码的解释。

单行文档注释

1
/// 单行文档注释

当我们用 ⌥ + 鼠标左键,点击代码时,可以查看属性或者方法的文档页面,更直观的查看代码的文档说明。

多数时候,我们都在使用这个方法注释类,结构体、枚举,属性,方法

多行注释

1
2
3
4
5
/*
第一行注释
第二行注释
第三行注释
*/

在代码中,如果连续很多个单行注释,可换成多行注释,避免写很多单行注释,造成多余代码。

多行文档注释

1
2
3
/**
多行文档注释
*/

可以在多行文档注释中加入一些 MD 语法,就可以达到文档页面的特殊样式。

注释中的标记语法

在 Xcode 中写 Swift 代码程序注释,本身就有其支持的 MarKDown 语法。还有一些特殊的标记,可以在右边 mini 代码预览中展示,也可以在最上边的文件路径层次里查看。

标记

1
2
// MARK: 这个是标示
// MARK: - 这个是带分割线的标示

用于标记代码结构,而且在 Xcode 中右边 mini map 中可以看到

1
2
// TODO: 这个下边要写一些代码,实现某个目的。
// TODO: - 多了一条分割线。

这个用来提示下一步编写代码的目的或者实现逻辑。

1
// FIXME: 这个地方要修理一下。

提示这个地方的代码需要修复,存在某种需要修复问题。

文档注释

在开发中,我们可以用 快捷键⌥ + ⌘ + / ,来为代码生成文档注释///

其中 - Parameters:写法,还有- Throws:- Returns:写法,都是特殊的关键字符格式,会在文档注释的页面特别显示。

1
2
3
4
5
6
7
8
9
10
11
/// 两个整数相加
/// - Parameters:
/// - a: 加号左边的整数
/// - b: 加号右边的整数
/// - Throws: 抛出错误,此方法不抛出错误,只为另外演示注释用法。
/// - Returns: 和
///
/// 这个是一个两个整数的相加方法,用于求两个整数的和。
func add(a: Int, b: Int) throws -> Int {
return a + b
}

可以在下图中的看到生成的文档样式,那些关键字起到一些标题的作用,让文档更清晰明了。而且是 Xcode 根据注释语法,自动生成的文档说明。

img

另外,在多行文档注释中,还可以使用 MarkDown 语法进行书写。还有一些其他的关键字,也可在注释文档中使用。可参照下边代码,或者自行学习 MarkDown 语法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
/**
两个整数相加
# 加法(标题一)
这个方法执行整数的加法运算。
## 加法运算(标题二)
想加个试试看

中间隔着一个横线
***

代码块的*使用*方法:
``(不用添加括号)`

let num = func add(a: 1, b: 2)
// print 3
``(不用添加括号)`

- c: 参数一
- d: 参数二
- f: 参数三

- Parameters:
- a: 加号左边的整数
- b: 加号右边的整数
- Throws: 抛出错误,此方法不抛出错误,只为另外演示注释用法。
- Returns: 和

- Important: 注意这个方法的参数。
- Version: 1.0.0
- Authors: Wei You, Fang Wang
- Copyright: 版权所有
- Date: 2020-12-28
- Since: 1949-10-01
- Attention: 加法的运算
- Note: 提示一下,用的时候请注意类型。
- Remark: 从新标记一下这个方法。
- Warning: 警告,这是一个没有内容的警告。
- Bug: 标记下bug问题。
- TODO: 要点改进的代码
- Experiment: 试验点新玩法。
- Precondition: 使用方法的前置条件
- Postcondition:使用方法的后置条件
- Requires: 要求一些东西,才能用这个方法。
- Invariant: 不变的
*/
func add(a: Int, b: Int) throws -> Int {
return a + b
}

变量或函数改名字

当我们更改了原来的变量名且不能直接删除变量而需要弃用时,[email protected]

变量abc需要更名为def

1
2
3
4
@available(*, unavailable, renamed: "def")
var abc = "hello"

var def = "hello"

函数改名

1
2
@available(*, deprecated, renamed: "loadData")
func fetchData() { }

变量或函数弃用

如果我们弃用函数或者变量,我们也可以标记

1
2
@available(*, deprecated, message: "Parse your data by hand instead")
func parseData() { }

指定最低支持的Swift版本

如果一些函数在高版本改名,我们可以用

1
2
@available(swift, obsoleted: 4.1, renamed: "attemptConnection")
func testConnection() { }

我们也可以弃用和最低支持一起使用

1
@available(swift, deprecated: 4.0, obsoleted: 5.0, message: "This will be removed in v5.0; please migrate to a different API.")

指定引入函数的版本

如果你需要指定引入这个函数的版本,可以用introduced

1
2
@available(swift, introduced: 4.2)
func loadUsers() { }

[email protected]自己的API一样–Xcode会在废弃的方法上画红线,发出编译警告和错误,甚至在需要时自动生成修复。