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

このコミットは、以前の変更（CL 6248054 / 0f418a63cdf9）を取り消すものです。取り消しの理由は、その変更がGo言語の公開APIドキュメントのスタイルを損なうためとされています。具体的には、src/pkg/net/file.go 内の FileListener 関数のコメントと引数名に関する変更が元に戻されています。

コミット

• コミットハッシュ: 14ad411407e539c7ebf478673f0afd9bf904af3c
• Author: Mikio Hara mikioh.mikioh@gmail.com
• Date: Wed May 30 01:42:36 2012 +0900

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

https://github.com/golang/go/commit/14ad411407e539c7ebf478673f0afd9bf904af3c

元コミット内容

このコミットが取り消している元のコミット（CL 6248054 / 0f418a63cdf9）の目的は、「net: fix comment on FileListener」と記載されています。これは、netパッケージ内の FileListener 関数に関するコメントを修正することを意図していました。

変更の背景

このコミット 14ad411407e539c7ebf478673f0afd9bf904af3c は、以前のコミット 0f418a63cdf9（CL 6248054）を元に戻すために作成されました。元に戻された理由は、その変更が「breaks public API document style」（公開APIドキュメントのスタイルを損なう）ためと明記されています。

Go言語では、関数の引数名もAPIドキュメントの一部として扱われることがあります。特に、関数のシグネチャとそれに付随するコメントは、GoDocなどのツールによって自動生成されるドキュメントに直接反映されます。元の変更では、FileListener 関数の戻り値の変数名が ln から l に変更され、それに伴いコメント内の参照も ln から l に、c から c に変更されていました。

このような変更は、一見すると単なる変数名のリファクタリングに見えますが、Goのドキュメンテーション規約においては、APIの安定性や一貫性を保つ上で重要な意味を持ちます。特に、公開APIのシグネチャやその説明は、ユーザーがコードを理解し、利用する上で非常に重要な情報源となります。変数名の変更がドキュメントの整合性を損なう、あるいは既存のドキュメントスタイルから逸脱すると判断されたため、この変更は取り消されることになりました。

前提知識の解説

• CL (Change List): Goプロジェクトでは、Gerritというコードレビューシステムが使われています。CLはChange Listの略で、Gerritにおける変更の単位を指します。GitHubのプルリクエストに似ていますが、GoプロジェクトではCLという用語が使われます。
• Go言語の net パッケージ: Go言語の標準ライブラリの一部で、ネットワークI/O機能を提供します。TCP/UDP接続、HTTPクライアント/サーバー、DNSルックアップなど、様々なネットワーク関連の機能が含まれています。
• os.File: Go言語の os パッケージで提供される型で、ファイルシステム上のファイルやデバイスを表します。ファイルディスクリプタをラップしており、ファイルに対する読み書き操作を行うことができます。
• net.Conn: ネットワーク接続の汎用インターフェースです。読み書き、ローカル/リモートアドレスの取得、接続のクローズなどのメソッドを定義しています。TCP接続やUDP接続など、具体的なネットワークプロトコルに依存しない形で接続を扱えます。
• net.Listener: ネットワークリスナーの汎用インターフェースです。ネットワークアドレスからの着信接続を待ち受け、新しい接続を受け入れるための Accept() メソッドを定義しています。TCPサーバーなどがこれを利用します。
• net.FileListener 関数: net パッケージ内の関数で、既存の os.File オブジェクトから net.Listener インターフェースを実装するオブジェクトを生成します。これは、例えば親プロセスから継承したファイルディスクリプタ（ソケットなど）をネットワークリスナーとして利用する際に役立ちます。
• GoのAPIドキュメンテーションスタイル: Go言語では、エクスポートされた（大文字で始まる）関数、変数、型、メソッドには、その直前にコメントを記述することで、GoDocツールによって自動的にドキュメントが生成されます。このコメントは、その要素の目的、引数、戻り値などを説明するもので、特に引数名や戻り値の変数名がコメント内で参照される場合、それらの名前の一貫性はドキュメントの可読性と正確性に直結します。

技術的詳細

このコミットは、src/pkg/net/file.go ファイル内の FileListener 関数の定義と関連するコメントを修正しています。

元の変更（CL 6248054）では、FileListener 関数の戻り値の変数名が ln から l に変更され、それに伴いコメント内の参照も変更されていました。

// FileListener returns a copy of the network listener corresponding
// to the open file f.  It is the caller's responsibility to close l
// when finished.  Closing c does not affect l, and closing l does not
// affect c.
func FileListener(f *os.File) (l Listener, err error) {

このコミットでは、この変更を元に戻し、戻り値の変数名を ln に、コメント内の参照も ln と f に戻しています。

// FileListener returns a copy of the network listener corresponding
// to the open file f.  It is the caller's responsibility to close ln
// when finished.  Closing ln does not affect f, and closing f does not
// affect ln.
func FileListener(f *os.File) (ln Listener, err error) {

Go言語の慣習として、関数の戻り値に名前を付ける場合、その名前は関数のドキュメンテーションの一部として扱われます。特に、コメント内でその戻り値の名前が参照される場合、その名前はAPIの利用者にとって重要な情報となります。

この変更が「公開APIドキュメントのスタイルを損なう」と判断されたのは、以下の理由が考えられます。

1. 一貫性の欠如: 既存のGoのコードベースやドキュメンテーションにおいて、Listener 型の変数には ln という名前が慣習的に使われている可能性が高いです。これを l に変更することは、既存の慣習や一貫性を破ると見なされた可能性があります。
2. ドキュメントの整合性: GoDocなどのツールは、関数のシグネチャとコメントを組み合わせてドキュメントを生成します。コメント内で ln と記述されているにもかかわらず、シグネチャが l になると、ドキュメントと実際のコードとの間に不整合が生じ、利用者を混乱させる可能性があります。
3. APIの安定性: Goでは、APIの安定性が非常に重視されます。変数名のような些細な変更であっても、それが公開APIのドキュメンテーションに影響を与える場合、互換性の問題や利用者の混乱を避けるために、変更が取り消されることがあります。特に、FileListener のような基本的な関数では、その影響は大きくなります。

このコミットは、機能的なバグ修正ではなく、Goプロジェクトにおけるコードスタイル、ドキュメンテーションの一貫性、およびAPIの安定性に対する厳格な姿勢を示すものです。

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

diff --git a/src/pkg/net/file.go b/src/pkg/net/file.go
index 8a0c40f61d..c95d16d64e 100644
--- a/src/pkg/net/file.go
+++ b/src/pkg/net/file.go
@@ -88,10 +88,10 @@ func FileConn(f *os.File) (c Conn, err error) {
 }
 
 // FileListener returns a copy of the network listener corresponding
-// to the open file f.  It is the caller's responsibility to close l
-// when finished.  Closing c does not affect l, and closing l does not
-// affect c.
-func FileListener(f *os.File) (l Listener, err error) {
+// to the open file f.  It is the caller's responsibility to close ln
+// when finished.  Closing ln does not affect f, and closing f does not
+// affect ln.
+func FileListener(f *os.File) (ln Listener, err error) {
 	fd, err := newFileFD(f)
 	if err != nil {
 		return nil, err

コアとなるコードの解説

この変更は、src/pkg/net/file.go ファイル内の FileListener 関数の定義と、その直前のコメントブロックに集中しています。

• コメントの変更:

  • - // to the open file f. It is the caller's responsibility to close l
  • + // to the open file f. It is the caller's responsibility to close ln
    • 元の変更で l となっていた部分が ln に戻されました。これは、FileListener が返す Listener インターフェースのインスタンスを指す変数名です。
  • - // when finished. Closing c does not affect l, and closing l does not
  • + // when finished. Closing ln does not affect f, and closing f does not
    • ここでも c が f に、l が ln に戻されています。これは、FileListener が受け取る os.File のインスタンスを指す f と、返す Listener のインスタンスを指す ln の間の関係を説明する部分です。元の変更では、FileConn 関数で使われる c (Conn) と l (Listener) の関係に合わせたコメントになっていましたが、FileListener の文脈では f (File) と ln (Listener) の関係を説明するのが適切です。
  • - // affect c.
  • + // affect ln.
    • 同様に、c が ln に戻されています。

• 関数シグネチャの変更:

  • - func FileListener(f *os.File) (l Listener, err error) {
  • + func FileListener(f *os.File) (ln Listener, err error) {
    • FileListener 関数の戻り値の変数名が l から ln に変更されました。Go言語では、戻り値に名前を付けることができます（named return parameters）。この名前は、関数内部でその戻り値を参照するために使われるだけでなく、GoDocなどのドキュメンテーションツールによって生成されるドキュメントにも表示されます。

このコミットは、FileListener 関数のコメントと戻り値の変数名を、Goプロジェクトの既存の慣習とドキュメンテーションスタイルに合致させるために元に戻すものです。これにより、APIドキュメントの一貫性と正確性が保たれます。

関連リンク

• 元の変更 (CL 6248054): https://golang.org/cl/6248054
• この変更 (CL 6242066): https://golang.org/cl/6242066

参考にした情報源リンク

• Go言語の公式ドキュメント (GoDocの仕組みやコメントの書き方に関する情報)
• Gerrit Code Review (CLの概念に関する情報)
• Web検索: "golang CL 6248054" (元のCLに関する情報)