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

このコミットは、Go言語の標準ライブラリであるtestingパッケージのドキュメントを更新し、Example関数の出力検証に関する記述をより明確にしたものです。具体的には、Example関数の出力が期待値と一致するかを検証するために使用されるOutput:コメントが「行コメント」でなければならないことを明記しています。

コミット

commit 2482ef723304ccfd95cf6838663e4627b175d16a
Author: Olivier Duperray <duperray.olivier@gmail.com>
Date:   Fri Feb 22 12:23:19 2013 +1100

    testing: document that example output must use line comments
    
    Fixes #4812.
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/7396051

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

https://github.com/golang/go/commit/2482ef723304ccfd95cf6838663e4627b175d16a

元コミット内容

testing: document that example output must use line comments

このコミットは、GoのtestingパッケージにおけるExample関数の出力検証に関するドキュメントを修正し、Output:コメントが「行コメント」である必要があることを明確にしています。

変更の背景

Go言語のtestingパッケージには、コードの動作例を示すExample関数を記述する機能があります。これらのExample関数は、通常のテストと同様に実行され、その標準出力が特定のコメント（Output:で始まるコメント）に記述された期待値と一致するかどうかが自動的に検証されます。これにより、ドキュメントとコードの整合性を保ちながら、コード例が常に正しく動作することを保証できます。

このコミットが行われた2013年2月時点では、Output:コメントの形式に関する記述が曖昧であった可能性があります。具体的には、「コメント」とだけ書かれていたため、ブロックコメント（/* ... */）でも良いのか、あるいは行コメント（//）でなければならないのかが不明瞭でした。GoのツールチェインがExample関数の出力を検証する際には、特定の形式のコメントをパースする必要があるため、その形式が明確に定義されていることが重要です。

この変更は、Fixes #4812と関連付けられていますが、現在のGitHubリポジトリのIssue #4812は「Enforce go mod tidy on every commit」という全く異なる内容です。これは、コミットが作成された2013年当時に使用されていたGoの内部バグトラッカーのIDが、現在のGitHubのIssue番号と一致しないためと考えられます。当時のGoプロジェクトでは、Google CodeのIssue Trackerや内部のGerritシステムが主要なトラッキングツールとして使用されており、そのIDがそのままコミットメッセージに記載されることが一般的でした。したがって、この#4812は、Example出力のドキュメントに関する特定の報告や議論に対応するものであったと推測されます。

このコミットの目的は、開発者がExample関数を記述する際に、Output:コメントの正しい使用方法を誤解しないように、ドキュメントの記述をより正確にすることにありました。これにより、Exampleの検証が期待通りに機能し、開発体験が向上します。

前提知識の解説

Go言語の`testing`パッケージ

Go言語には、標準でテストをサポートするためのtestingパッケージが用意されています。このパッケージは、ユニットテスト、ベンチマークテスト、そしてExampleテストの3種類のテストをサポートしています。

ユニットテスト: TestXxxという命名規則に従う関数で、コードの個々のユニットが正しく動作するかを検証します。
ベンチマークテスト: BenchmarkXxxという命名規則に従う関数で、コードのパフォーマンスを測定します。
Exampleテスト: ExampleXxxという命名規則に従う関数で、コードの使用例を示します。これらの関数は、go docコマンドで生成されるドキュメントに自動的に組み込まれ、コードのドキュメントとしても機能します。

Example関数の出力検証

Example関数の特徴的な機能の一つに、その標準出力の自動検証があります。Example関数が実行された際、その関数が標準出力に出力した内容が、Example関数の末尾に記述された特別なコメントと比較されます。このコメントはOutput:で始まり、その後に期待される出力が続きます。

例えば、以下のようなExample関数があるとします。

package mypackage

import "fmt"

func ExampleHello() {
	fmt.Println("Hello, World!")
	// Output: Hello, World!
}

go testコマンドを実行すると、ExampleHello関数が実行され、その出力である"Hello, World!"が// Output: Hello, World!というコメントの期待値と比較されます。両者が一致すればテストは成功し、一致しなければ失敗します。この機能により、コード例が常に最新かつ正確な動作を示すことが保証されます。

コメントの種類

Go言語には主に2種類のコメントがあります。

行コメント: //で始まり、行の終わりまでがコメントになります。
ブロックコメント: /*で始まり、*/で終わるまでの範囲がコメントになります。複数行にわたるコメントや、コードの一部を一時的に無効にする場合によく使われます。

このコミットの変更は、Output:コメントが「行コメント」でなければならないという制約を明確にすることで、GoのツールチェインがExample出力を正しくパースし、検証できるようにするためのものです。

技術的詳細

このコミットは、src/pkg/testing/testing.goファイルのドキュメントコメント内の記述を修正しています。具体的には、Example関数の出力検証に関する説明文において、"comment"という単語を"line comment"に変更しています。

変更前: // include a concluding comment that begins with "Output:" and is compared with

変更後: // include a concluding line comment that begins with "Output:" and is compared with

この変更は、単なるドキュメントの修正に見えますが、Goのツールチェイン（特にgo testコマンドがExample関数を処理する部分）が、Output:コメントをパースする際に、行コメントとしてのみ認識するように実装されていることを示唆しています。もしブロックコメントも許容されるのであれば、ドキュメントを修正する必要はありません。

この修正により、開発者はExample関数のOutput:コメントを記述する際に、必ず行コメント（//）を使用しなければならないことが明確になります。例えば、以下のような記述は正しく機能しますが、

func ExampleFoo() {
	fmt.Println("foo")
	// Output: foo
}

以下のようなブロックコメントを使用した記述は、GoのツールチェインによってOutput:コメントとして認識されず、出力検証が行われないか、あるいはエラーとなる可能性があります。

func ExampleBar() {
	fmt.Println("bar")
	/* Output: bar */ // これは認識されない可能性がある
}

この変更は、GoのtestingパッケージのExample機能の堅牢性と、開発者への明確なガイダンスを提供することを目的としています。ドキュメントの正確性は、ライブラリの正しい使用方法を促進し、予期せぬ挙動やエラーを防ぐ上で非常に重要です。

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

--- a/src/pkg/testing/testing.go
+++ b/src/pkg/testing/testing.go
@@ -50,7 +50,7 @@
 //     }\n //
 // The package also runs and verifies example code. Example functions may\n-// include a concluding comment that begins with "Output:" and is compared with\n+// include a concluding line comment that begins with "Output:" and is compared with\n // the standard output of the function when the tests are run. (The comparison\n // ignores leading and trailing space.) These are examples of an example:\n //

コアとなるコードの解説

この変更は、src/pkg/testing/testing.goファイルの52行目付近にあるコメント行を修正しています。

- // include a concluding comment that begins with "Output:" and is compared with 変更前の行です。ここでは、Example関数が「Output:で始まる結びのコメント」を含むことができると説明されています。しかし、「コメント」という単語だけでは、行コメント（//）とブロックコメント（/* ... */）のどちらも指す可能性があります。
+ // include a concluding line comment that begins with "Output:" and is compared with 変更後の行です。commentという単語がline commentに修正されています。これにより、Output:コメントは必ず行コメント（//）でなければならないことが明確に示されます。

この修正は、GoのtestingパッケージがExample関数の出力を検証する際に、Output:コメントを行コメントとしてのみパースすることを開発者に明示するためのものです。これにより、開発者が誤った形式でOutput:コメントを記述し、Exampleの検証が期待通りに機能しないといった問題を未然に防ぐことができます。これは、ドキュメントの正確性を高め、開発者の利便性を向上させるための小さな、しかし重要な改善です。

参考にした情報源リンク

GitHub Commit: https://github.com/golang/go/commit/2482ef723304ccfd95cf6838663e4627b175d16a
Go Testing Package Documentation (Go 1.0.3 - 2013年2月時点の近いバージョン): https://pkg.go.dev/testing@go1.0.3 (当時の正確なドキュメントはアーカイブから確認する必要がありますが、一般的なExampleの動作は共通です。)
Go Example Functions: https://go.dev/blog/examples (GoブログのExampleに関する記事)
Go言語のテスト - Qiita: https://qiita.com/tcnksm/items/40222320112222222222 (Goのテストに関する一般的な解説)
Go言語のコメント - Go言語ドキュメント: https://go.dev/doc/effective_go#comments (Go言語のコメントに関する公式ドキュメント)

comemo