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程序中通?？梢曰煊脙煞N注釋形式。注釋對一般用于多行解釋，而雙斜線注釋則常用于半行或單行的標記。太多的注釋混入程序代碼可能會使代碼難以理解，通常最好是將一個注釋塊放在所解釋代碼的上方。

當改變代碼時，注釋應與代碼保持一致。程序員即使知道系統其他形式的文檔已經過期，還是會信任注釋，認為它是正確的。錯誤的注釋比沒有注釋更糟，因為它會誤導后來者。

在Swift程序中使用注釋時，必須遵循如下所示的原則。

禁止亂用注釋。

注釋必須和被注釋內容一致，不能描述與其無關的內容。

注釋要放在被注釋內容的上方或被注釋語句的后面。

函數頭部需要注釋，主要包含文件名、作者信息、功能信息和版本信息。

注釋對不可嵌套：注釋總是以“/*”開始并以“/*”結束。這意味著，一個注釋對不能出現在另一個注釋對中。由注釋對嵌套導致的編譯器錯誤信息容易使人迷惑。

注意：Swift編程風格

（1）在程序需要時，使用注釋說明一塊代碼為什么這么做。注釋必須時刻跟進代碼，不然刪掉。

（2）因為代碼應該盡可能的自文檔化，所以避免在代碼中使用成塊的注釋。另外：該規則不適用于生成文檔的成塊注釋。