2.5　注释

在通常情况下，注释是说明你的代码做些什么，具有什么功能。在Swift程序中，将非执行文本写为注释提示或者笔记的方式以方便将来进行阅读。Swift编译器将会在编译代码时自动忽略掉注释部分。在本节的内容中，将详细讲解Swift注释的基本知识。

2.5.1　注释的规则

在Swift语言中，通过使用注释可以帮助阅读程序，通常用于概括算法、确认变量的用途或者阐明难以理解的代码段。注释并不会增加可执行程序的大小，编译器会忽略所有注释。Swift中有两种类型的注释，分别是单行注释和成对注释。单行注释以双斜线“//”开头，行中处于双斜杠右边的内容是注释，被编译器忽略。例如如下所示的演示代码。

//这是一个注释

另一种是定界符：注释对（/**/），是从C语言继承过来的。这种注释以“/*”开头，以“*/”结尾，编译器将落入注释对“/**/”之间的内容作为注释。例如如下所示的演示代码。

/*这是一个，

多行注释*/

与C语言多行注释不同，Swift的多行注释可以嵌套在其他的多行注释中。例如，可以先生成一个多行注释块，然后在这个注释块之中再嵌套成第二个多行注释。在终止注释时，先插入第二个注释块的终止标记，然后再插入第一个注释块的终止标记。例如如下所示的演示代码。

通过运用嵌套多行注释，你可以快速方便的注释掉一大段代码，即使这段代码之中已经含有多行注释块。

由此可见，Swift和C++的注释几乎是相同的，也支持单行注释（用“//”进行注释）和多行注释（用“/* ... */进行注释）。不过Swift语言对其进行了扩展，在多行注释中可以嵌套多行注释。例如，右面的注释在Swift程序中是合法的。

实例文件main.swift的具体实现代码如下所示。

在下面的代码中，“var pi=3.14”表示定义了一个变量pi，初始值是3.14

本实例执行后的效果如图2-6所示。

2.5.2　使用注释的注意事项

在Swift语言中，可以在任何允许有制表符、空格或换行符的地方放置注释对。注释对可跨越程序的多行，但不是一定非要如此。当注释跨越多行时，最好能直观地指明每一行都是注释的一部分。我们的风格是在注释的每一行以星号开始，指明整个范围是多行注释的一部分。

在Swift程序中通常可以混用两种注释形式。注释对一般用于多行解释，而双斜线注释则常用于半行或单行的标记。太多的注释混入程序代码可能会使代码难以理解，通常最好是将一个注释块放在所解释代码的上方。

当改变代码时，注释应与代码保持一致。程序员即使知道系统其他形式的文档已经过期，还是会信任注释，认为它是正确的。错误的注释比没有注释更糟，因为它会误导后来者。

在Swift程序中使用注释时，必须遵循如下所示的原则。

禁止乱用注释。

注释必须和被注释内容一致，不能描述与其无关的内容。

注释要放在被注释内容的上方或被注释语句的后面。

函数头部需要注释，主要包含文件名、作者信息、功能信息和版本信息。

注释对不可嵌套：注释总是以“/*”开始并以“/*”结束。这意味着，一个注释对不能出现在另一个注释对中。由注释对嵌套导致的编译器错误信息容易使人迷惑。

注意：Swift编程风格

（1）在程序需要时，使用注释说明一块代码为什么这么做。注释必须时刻跟进代码，不然删掉。

（2）因为代码应该尽可能的自文档化，所以避免在代码中使用成块的注释。另外：该规则不适用于生成文档的成块注释。