gopl-zh.github.com/ch11/ch11-06.md

## 11.6. 示例函數

第三種`go test`特别處理的函數是示例函數，以Example爲函數名開頭。示例函數沒有函數參數和返迴值。下面是IsPalindrome函數對應的示例函數：

```Go
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語言特性最快捷的方式。

![](../images/ch11-04.png)

本書最後的兩掌是討論reflect和unsafe包，一般的Go用戶很少直接使用它們。因此，如果你還沒有寫過任何眞實的Go程序的話，現在可以忽略剩餘部分而直接編碼了。