[インデックス 11215] ファイルの概要

このコミットは、Go言語の標準ライブラリであるtestingパッケージのドキュメントを更新し、Goのテストフレームワークにおける「Example」機能について明示的に記述を追加するものです。これにより、go testコマンドがExample関数をどのように実行し、検証するかについての情報が、パッケージの公式ドキュメント内で利用可能になります。

コミット

commit 3b87d68a07a5a5f324d40dfe13b6d725c4af2135
Author: Rob Pike <r@golang.org>
Date:   Tue Jan 17 14:20:27 2012 -0800

    testing: document examples
    The package documentation did not mention them.
    They were described only in godoc for gotest, and that's going away.
    
    R=golang-dev, rsc, adg
    CC=golang-dev
    https://golang.org/cl/5539079

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/3b87d68a07a5a5f324d40dfe13b6d725c4af2135

元コミット内容

このコミットの目的は、「testing」パッケージのドキュメントにExample関数に関する記述を追加することです。これまでExample関数は、gotestユーティリティのgodoc（ドキュメント）でのみ説明されていましたが、そのgotestが廃止される予定であったため、testingパッケージ自体のドキュメントにこの重要な情報を移管する必要がありました。

変更の背景

この変更の背景には、Go言語のテストツールチェインの進化があります。初期のGoでは、テストの実行にgotestという独立したユーティリティが使われていました。しかし、Go 1のリリースに向けて、テスト機能はgo testというコマンドに統合され、よりシンプルで一貫性のあるワークフローが提供されることになりました。

gotestの廃止に伴い、そのドキュメントにのみ存在していたExample関数の説明が失われることになります。Example関数は、コードの利用例を示すだけでなく、テストの一部として自動的に実行・検証されるという非常に有用な機能です。そのため、この重要な機能に関するドキュメントが失われることを防ぎ、かつ、testingパッケージの利用者が容易にその存在と使い方を理解できるように、パッケージ自体のドキュメントにExample関数の説明を組み込む必要がありました。

このコミットは、Go 1のリリースに向けたドキュメントの整備の一環であり、ユーザーがGoのテスト機能をより効果的に活用できるようにするための基盤を固めるものでした。

前提知識の解説

Go言語のtestingパッケージ

Go言語には、標準ライブラリとしてtestingパッケージが提供されており、ユニットテスト、ベンチマークテスト、そしてExample（例示）コードの記述と実行をサポートします。

• ユニットテスト: func TestXxx(*testing.T)という形式の関数で記述されます。go testコマンドを実行すると、これらの関数が自動的に発見され、実行されます。*testing.T型は、テストの失敗を報告したり、ログを出力したりするためのメソッドを提供します。
• ベンチマークテスト: func BenchmarkXxx(*testing.B)という形式の関数で記述されます。go test -bench=.のように-benchフラグを付けて実行すると、コードのパフォーマンスを測定できます。*testing.B型は、ベンチマークの反復回数を制御するb.Nフィールドを提供します。
• Example関数: func ExampleXxx()、func ExampleT()、func ExampleT_M()といった形式で記述されます。これらは、特定の関数、型、またはメソッドの利用例を示すためのコードスニペットです。Example関数は、単なるドキュメントとしてだけでなく、go testコマンドによって自動的にコンパイルされ、実行され、その標準出力がコメントに記述された期待される出力と一致するかどうかが検証されます。これにより、ドキュメントの正確性が保証されます。

go testコマンド

go testは、Goのソースコードをテストするためのコマンドラインツールです。プロジェクト内のテストファイル（通常は_test.goで終わるファイル）を自動的に探し、その中のTestXxx、BenchmarkXxx、ExampleXxx関数を実行します。

• go test: テストを実行し、結果を表示します。
• go test -v: 詳細なテスト結果を表示します。
• go test -bench=.: ベンチマークテストを実行します。
• go test -run Example: Example関数のみを実行し、検証します。

godoc

godocは、Goのソースコードからドキュメントを生成・表示するためのツールです。Goのコードコメント（特にパッケージ、関数、型、メソッドの宣言の直前にあるコメント）を解析し、HTML形式などで表示します。これにより、開発者はコードとドキュメントを密接に連携させることができます。

技術的詳細

このコミットは、testingパッケージのパッケージコメント（doc.goまたはパッケージを定義するファイルの先頭コメント）にExample関数に関する詳細な説明を追加することで、ドキュメントの網羅性を高めています。

追加された内容は以下の通りです。

1. Example関数の目的: Example関数がコード例を提供し、go testによって検証されることを説明しています。
2. Example関数の構造: Example関数は、その標準出力が期待される出力と一致するかどうかを検証するために、通常、関数の直前にコメント（期待される出力）を持つことを示しています。

   // hello
   func ExampleHello() {
           fmt.Println("hello")
   }
   

   コメントがないExample関数はコンパイルされますが、実行はされません。
3. 命名規則: 関数F、型T、および型TのメソッドMに対するExample関数の命名規則を明確にしています。
   • 関数Fの例: func ExampleF() { ... }
   • 型Tの例: func ExampleT() { ... }
   • 型TのメソッドMの例: func ExampleT_M() { ... }
4. 複数のExample関数: 同じ関数/型/メソッドに対して複数のExample関数を提供する場合、名前に小文字で始まる一意のサフィックスを追加できることを説明しています。
   • func ExampleF_suffix() { ... }
   • func ExampleT_suffix() { ... }
   • func ExampleT_M_suffix() { ... }

これらの説明は、GoのExample機能の強力な側面を強調し、開発者がどのようにExampleを記述し、それらがどのようにテストスイートに統合されるかを明確にしています。これにより、Goのドキュメントは単なる説明書ではなく、実行可能なコード例を含む「ライブドキュメント」としての価値を高めています。

コアとなるコードの変更箇所

変更はsrc/pkg/testing/testing.goファイルに対して行われています。

--- a/src/pkg/testing/testing.go
+++ b/src/pkg/testing/testing.go
@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // Package testing provides support for automated testing of Go packages.
-// It is intended to be used in concert with the ``gotest\'\' utility, which automates
+// It is intended to be used in concert with the ``go test\'\' command, which automates
 // execution of any function of the form
 //     func TestXxx(*testing.T)
 // where Xxx can be any alphanumeric string (but the first letter must not be in
@@ -21,6 +21,7 @@
 //             fmt.Sprintf(\"hello\")
 //         }\n //     }\n+//
 // The benchmark package will vary b.N until the benchmark function lasts
 // long enough to be timed reliably.  The output
 //     testing.BenchmarkHello    10000000    282 ns/op
@@ -36,6 +37,33 @@
 //             big.Len()\n //         }\n //     }\n+//\n+// The package also runs and verifies example code. Example functions
+// include an introductory comment that is compared with the standard output
+// of the function when the tests are run, as in this example of an example:\n+//\n+//     // hello\n+//     func ExampleHello() {\n+//             fmt.Println(\"hello\")\n+//     }\n+//\n+// Example functions without comments are compiled but not executed.\n+//\n+// The naming convention to declare examples for a function F, a type T and\n+// method M on type T are:\n+//\n+//     func ExampleF() { ... }\n+//     func ExampleT() { ... }\n+//     func ExampleT_M() { ... }\n+//\n+// Multiple example functions for a type/function/method may be provided by\n+// appending a distinct suffix to the name. The suffix must start with a\n+// lower-case letter.\n+//\n+//     func ExampleF_suffix() { ... }\n+//     func ExampleT_suffix() { ... }\n+//     func ExampleT_M_suffix() { ... }\n+//\n package testing
 
 import (

具体的には、以下の変更が行われています。

1. gotestからgo testへの言及の変更: - It is intended to be used in concert with the ``gotest\'\' utility, which automates + It is intended to be used in concert with the ``go test\'\' command, which automates これは、前述のgotestの廃止とgo testへの移行を反映したものです。
2. Example関数に関する新しいドキュメントブロックの追加: ベンチマーク関数の説明の後に、Example関数に関する詳細な説明が追加されています。これには、Example関数の目的、構造、命名規則、および複数のExample関数を記述する方法が含まれます。

コアとなるコードの解説

このコミットの「コアとなるコード」は、Goのtestingパッケージのドキュメントコメントそのものです。Goでは、パッケージのドキュメントは通常、そのパッケージを定義するGoファイルの先頭にあるコメントブロックに記述されます。このコメントはgodocツールによって解析され、公式ドキュメントとして公開されます。

追加されたコメントは、GoのExample機能の利用方法を明確に説明しています。

• The package also runs and verifies example code. Exampleコードが単に実行されるだけでなく、「検証される」という点が重要です。これは、Example関数の出力が期待される出力と一致するかどうかをgo testが自動的にチェックすることを意味します。
• Example functions include an introductory comment that is compared with the standard output of the function when the tests are run, as in this example of an example: Example関数の直前のコメントが、その関数の標準出力と比較されるというメカニズムを説明しています。これにより、ドキュメント内のコード例が常に最新かつ正確であることが保証されます。
• Example functions without comments are compiled but not executed. コメントがないExample関数はコンパイルエラーを防ぐためにチェックされますが、出力検証は行われないことを示しています。
• 命名規則の説明 (ExampleF, ExampleT, ExampleT_M, ExampleF_suffixなど) は、開発者がExample関数をどのように命名すべきか、そしてそれらがどのように特定のコード要素に関連付けられるかを明確にしています。これにより、go testがExample関数を正しく発見し、実行できるようになります。

このドキュメントの追加により、testingパッケージの利用者は、Example機能の存在と、それを効果的に利用するためのすべての必要な情報を、パッケージの公式ドキュメント内で見つけることができるようになりました。これは、Goのテストとドキュメンテーションの品質向上に大きく貢献しています。

関連リンク

• https://github.com/golang/go/commit/3b87d68a07a5a5f324d40dfe13b6d725c4af2135
• https://golang.org/cl/5539079 (Go Code Review - testing: document examples)

参考にした情報源リンク

• Go 1 Release Notes (特にTestingに関するセクション): https://go.dev/doc/go1 (当時のGo 1リリースノートは、go testへの移行について言及している可能性があります)
• Goのtestingパッケージのドキュメント: https://pkg.go.dev/testing (現在のドキュメントは、このコミットで追加された内容を含んでいます)
• Go Example Functions: https://go.dev/blog/examples (GoブログのExample関数に関する記事。このコミットの背景にある思想を理解するのに役立ちます)
• go testコマンドのドキュメント: https://go.dev/cmd/go/#hdr-Test_packages