Go 語言 示例函數(shù)

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

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

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

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

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