11.6. 示例函數

第三種被go test特別對待的函數是示例函數，以Example為函數名開頭。示例函數沒有函數參數和返回值。下面是IsPalindrome函數對應的示例函數：

func ExampleIsPalindrome() {
    fmt.Println(IsPalindrome("A man, a plan, a canal: Panama"))
    fmt.Println(IsPalindrome("palindrome"))
    // Output:
    // true
    // false
}

示例函數有三個用處。最主要的一個是作為文檔：一個包的例子可以更簡潔直觀的方式來演示函數的用法，比文字描述更直接易懂，特別是作為一個提醒或快速參考時。一個示例函數也可以方便展示屬於同一個接口的幾種類型或函數之間的關係，所有的文檔都必須關聯到一個地方，就像一個類型或函數聲明都統一到包一樣。同時，示例函數和註釋並不一樣，示例函數是真實的Go代碼，需要接受編譯器的編譯時檢查，這樣可以保證源代碼更新時，示例代碼不會脫節。

根據示例函數的後綴名部分，godoc這個web文檔服務器會將示例函數關聯到某個具體函數或包本身，因此ExampleIsPalindrome示例函數將是IsPalindrome函數文檔的一部分，Example示例函數將是包文檔的一部分。

示例函數的第二個用處是，在go test執行測試的時候也會運行示例函數測試。如果示例函數內含有類似上面例子中的// Output:格式的註釋，那麼測試工具會執行這個示例函數，然後檢查示例函數的標準輸出與註釋是否匹配。

示例函數的第三個目的提供一個真實的演練場。 http://golang.org 就是由godoc提供的文檔服務，它使用了Go Playground讓用戶可以在瀏覽器中在線編輯和運行每個示例函數，就像圖11.4所示的那樣。這通常是學習函數使用或Go語言特性最快捷的方式。

本書最後的兩章是討論reflect和unsafe包，一般的Go程序員很少使用它們，事實上也很少需要用到。因此，如果你還沒有寫過任何真實的Go程序的話，現在可以先去寫些代碼了。