原文鏈接：https://gopl-zh.github.io/ch11/ch11-06.html

11.6. 示例函數(shù)

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

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

示例函數(shù)有三個(gè)用處。最主要的一個(gè)是作為文檔：一個(gè)包的例子可以更簡潔直觀的方式來演示函數(shù)的用法，比文字描述更直接易懂，特別是作為一個(gè)提醒或快速參考時(shí)。一個(gè)示例函數(shù)也可以方便展示屬于同一個(gè)接口的幾種類型或函數(shù)之間的關(guān)系，所有的文檔都必須關(guān)聯(lián)到一個(gè)地方，就像一個(gè)類型或函數(shù)聲明都統(tǒng)一到包一樣。同時(shí)，示例函數(shù)和注釋并不一樣，示例函數(shù)是真實(shí)的Go代碼，需要接受編譯器的編譯時(shí)檢查，這樣可以保證源代碼更新時(shí)，示例代碼不會(huì)脫節(jié)。

根據(jù)示例函數(shù)的后綴名部分，godoc這個(gè)web文檔服務(wù)器會(huì)將示例函數(shù)關(guān)聯(lián)到某個(gè)具體函數(shù)或包本身，因此ExampleIsPalindrome示例函數(shù)將是IsPalindrome函數(shù)文檔的一部分，Example示例函數(shù)將是包文檔的一部分。

示例函數(shù)的第二個(gè)用處是，在go test執(zhí)行測試的時(shí)候也會(huì)運(yùn)行示例函數(shù)測試。如果示例函數(shù)內(nèi)含有類似上面例子中的// Output:格式的注釋，那么測試工具會(huì)執(zhí)行這個(gè)示例函數(shù)，然后檢查示例函數(shù)的標(biāo)準(zhǔn)輸出與注釋是否匹配。

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

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