如何在 Swift 中使用注释

在开发软件的过程中，往往耗费时间最长的不是编码而是查看代码，无论是去理解同事写的代码，还是查看系统的 API，亦或是回忆自己原来所写的代码。能在最短的时间内理解类型和函数的作用，除了良好的函数命名以外，注释也是必不可少的。虽然我个人更喜欢用有自注解能力的函数和类命令，但是在遇见复杂逻辑时，过长、过于详细的方法名会使得在调用时显得过于啰嗦。对于通用型、调用频繁的的类型和函数，我更喜欢使用简化的函数声明，然后辅以更加详细的注释，这样在初次使用此函数时，可以通过注释快速了解调用方法，在调用时简洁明了。

在 Swift 当中，注释的用法有很多种，包括描述、参数声明、高亮显示、实例代码、加粗显示灯，下面一一介绍一下：

在一个类中，给一个属性加上一个描述有几种写法，首先是 // 我是注释 和 /* 我是注释 */ 两种写法，这两种写法的注释在你调用函数和属性的时候，在编译器的智能提示当中是不会显示注释内容的

而使用 // 我是注释 和 /** 我是注释 */ 的注释方法会在编译器智能提示的时候显示注释内容。

在注释当中如果要凸显一个类型、变量。我们可以使用单引号 ` Class ` 将内容括起来，这样在注释当中就会高亮显示，通常用来高亮 类名、方法名、和值。

方法的注释中主要涉及到了方法描述、参数注释、返回值注释。下面是 Swift 当中的两种注释方法，他们的差距不大，第一种适合在参数较多的时候使用，不用重复写 Parameter, 第二种适合在单个参数的时候使用,显得注释更加的紧凑。

对于一些不易理解的方法，举例子显然更有效，现在我们就在注释中加入一个例子：

例子的代码 向前要有5 个空格，向上要留一个空行，才能显示出高亮

在一个文件当中，大家都喜欢把相关的代码写在一块，这样看起来简洁，找起来的方便。通常我们可以使用 // MARK: 我是注释 和 // MARK: - 我是注释 来分割代码，中间有一个 -的话在 Xcode 右侧的 miniMap 中就能显示出一条分割线。如果在一个方法的内部我们也想对内容进行区分，或是分割一个长长的注释。我们需要一个局部显眼，而全局不突兀的注释。

底部用等号 = 填充，向前空一个空格，上面的字符就会被加粗高亮显示

特殊标记

• /// - TODO:
• /// - Warning:
• /// - Important:
• /// - Version:
• /// - Authors:
• /// - Copyright:
• /// - Date:
• /// - Since:
• /// - Attention:
• /// - Note:
• /// - Remark:
• /// - Warning:
• /// - Bug:
• /// - TODO:
• /// - Experiment:
• /// - Precondition:
• /// - Postcondition:
• /// - Requires:
• /// - Invariant:

注释写得好，下班下得早