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

このコミットは、Go言語の標準ライブラリであるnetパッケージ内のAcceptTCPおよびAcceptUnix関数のドキュメンテーションの不正確さを修正するものです。具体的には、これらの関数が「リモートアドレス」を個別の戻り値として返すかのような記述を削除し、単に「新しい接続」を返すことを明確にしています。

コミット

commit a3834a2e8a730a4e6a9be9f7ebba96ec3c942d32
Author: Kamil Kisiel <kamil@kamilkisiel.net>
Date:   Fri Sep 6 12:00:03 2013 -0700

    net: Fix inaccurate docs for AcceptTCP and AcceptUnix.
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/13592043

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

https://github.com/golang/go/commit/a3834a2e8a730a4e6a9be9f7ebba96ec3c942d32

元コミット内容

net: Fix inaccurate docs for AcceptTCP and AcceptUnix.

このコミットは、netパッケージのAcceptTCPおよびAcceptUnix関数のドキュメンテーションが不正確であったため、それを修正することを目的としています。

変更の背景

Go言語のnetパッケージは、ネットワークプログラミングのための基本的なインターフェースを提供します。TCPListenerやUnixListenerのようなリスナー型は、着信接続を受け入れるためのAcceptメソッド群を提供します。これらのメソッドは通常、新しい接続を表すオブジェクトと、エラーを返します。

このコミットが行われた時点（2013年）では、AcceptTCPおよびAcceptUnix関数のコメントには、「新しい接続とリモートアドレスを返す」という記述がありました。しかし、これらの関数が実際に返すのは、新しい接続を表す*TCPConnまたは*UnixConnオブジェクトのみであり、リモートアドレスはこれらの接続オブジェクトのメソッド（例: RemoteAddr())を通じて取得される情報でした。

ドキュメンテーションは、APIの正確な振る舞いを反映している必要があります。不正確なドキュメンテーションは、開発者がAPIを誤解し、誤ったコードを書く原因となる可能性があります。このコミットは、このような誤解を避けるために、ドキュメンテーションを実際のAPIの振る舞いに合わせて修正することを目的としています。これは、コードの正確性と保守性を高めるための一般的なプラクティスの一環です。

前提知識の解説

Go言語のnetパッケージ: Go言語の標準ライブラリの一部で、TCP/IP、UDP、Unixドメインソケットなどのネットワーク通信機能を提供します。クライアントとサーバーの両方のアプリケーションを構築するために使用されます。
net.Listenerインターフェース: ネットワーク接続をリッスンするための一般的なインターフェースです。Accept()メソッドを持ち、新しい接続が確立されるのを待ち、その接続を返します。
net.TCPListener: TCPネットワーク接続をリッスンするための具体的な型です。AcceptTCP()メソッドを持ち、TCP接続を受け入れます。
net.UnixListener: Unixドメインソケット接続をリッスンするための具体的な型です。AcceptUnix()メソッドを持ち、Unixドメインソケット接続を受け入れます。
Acceptメソッドの役割: サーバーサイドのネットワークプログラミングにおいて、Acceptメソッドは、クライアントからの新しい接続要求を受け入れ、その接続を処理するための新しいソケット（または接続オブジェクト）を確立する役割を担います。通常、このメソッドはブロッキング呼び出しであり、新しい接続が来るまで待機します。
*TCPConn / *UnixConn: AcceptTCPやAcceptUnixが返す接続オブジェクトです。これらのオブジェクトは、確立されたネットワーク接続を表し、データの送受信や、接続に関する情報（ローカルアドレス、リモートアドレスなど）の取得のためのメソッドを提供します。
ドキュメンテーションの重要性: ソフトウェア開発において、ドキュメンテーションはコードの理解、使用、保守に不可欠です。特にAPIのドキュメンテーションは、そのAPIが何を行い、どのような引数を取り、どのような値を返すのかを正確に記述する必要があります。不正確なドキュメンテーションは、開発者の生産性を低下させ、バグの原因となる可能性があります。

技術的詳細

このコミットは、Go言語のnetパッケージ内の特定のファイルのコメント行を変更するものです。影響を受けるファイルは以下の通りです。

src/pkg/net/tcpsock_plan9.go
src/pkg/net/tcpsock_posix.go
src/pkg/net/unixsock_plan9.go
src/pkg/net/unixsock_posix.go

これらのファイルは、それぞれPlan 9およびPOSIX（Linux, macOSなどのUnix系OS）環境におけるTCPソケットとUnixドメインソケットの実装に関連しています。Go言語はクロスプラットフォームを強く意識しており、OS固有のシステムコールやAPIを抽象化するために、このようなOSごとの実装ファイルを持つことが一般的です。

変更内容は非常にシンプルで、AcceptTCPおよびAcceptUnix関数のGoDocコメント（関数の直前にあるコメントで、go docコマンドやGoのドキュメンテーションサイトで表示されるもの）から、「and the remote address.」というフレーズを削除しています。

修正前: // connection and the remote address.

修正後: // connection.

これは、AcceptTCPが(*TCPConn, error)を返し、AcceptUnixが(*UnixConn, error)を返すという事実に基づいています。これらの関数は、接続オブジェクト自体を返しますが、リモートアドレスは接続オブジェクトのメソッド（例: conn.RemoteAddr())を通じてアクセスされる属性であり、関数の直接の戻り値ではありません。

この変更は、コードの動作には一切影響を与えません。純粋にドキュメンテーションの正確性を向上させるためのものです。しかし、正確なドキュメンテーションは、ライブラリの使いやすさと信頼性を高める上で非常に重要です。

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

このコミットによる変更は、以下の4つのファイルのコメント行に限定されています。

src/pkg/net/tcpsock_plan9.go

--- a/src/pkg/net/tcpsock_plan9.go
+++ b/src/pkg/net/tcpsock_plan9.go
@@ -111,7 +111,7 @@ type TCPListener struct {
 }
 
 // AcceptTCP accepts the next incoming call and returns the new
-// connection and the remote address.
+// connection.
 func (l *TCPListener) AcceptTCP() (*TCPConn, error) {
 	if l == nil || l.fd == nil || l.fd.ctl == nil {
 		return nil, syscall.EINVAL

src/pkg/net/tcpsock_posix.go

--- a/src/pkg/net/tcpsock_posix.go
+++ b/src/pkg/net/tcpsock_posix.go
@@ -225,7 +225,7 @@ type TCPListener struct {
 }
 
 // AcceptTCP accepts the next incoming call and returns the new
-// connection and the remote address.
+// connection.
 func (l *TCPListener) AcceptTCP() (*TCPConn, error) {
 	if l == nil || l.fd == nil {
 		return nil, syscall.EINVAL

src/pkg/net/unixsock_plan9.go

--- a/src/pkg/net/unixsock_plan9.go
+++ b/src/pkg/net/unixsock_plan9.go
@@ -97,7 +97,7 @@ func ListenUnix(net string, laddr *UnixAddr) (*UnixListener, error) {
 }
 
 // AcceptUnix accepts the next incoming call and returns the new
-// connection and the remote address.
+// connection.
 func (l *UnixListener) AcceptUnix() (*UnixConn, error) {
 	return nil, syscall.EPLAN9
 }

src/pkg/net/unixsock_posix.go

--- a/src/pkg/net/unixsock_posix.go
+++ b/src/pkg/net/unixsock_posix.go
@@ -275,7 +275,7 @@ func ListenUnix(net string, laddr *UnixAddr) (*UnixListener, error) {
 }
 
 // AcceptUnix accepts the next incoming call and returns the new
-// connection and the remote address.
+// connection.
 func (l *UnixListener) AcceptUnix() (*UnixConn, error) {
 	if l == nil || l.fd == nil {
 		return nil, syscall.EINVAL

コアとなるコードの解説

上記の変更箇所は、Go言語のドキュメンテーションコメントの修正です。Go言語では、エクスポートされた関数、メソッド、型、変数などの直前に記述されたコメントは、GoDocツールによって自動的にドキュメンテーションとして抽出されます。

変更前は、AcceptTCPおよびAcceptUnix関数のコメントが以下のように記述されていました。

// AcceptTCP accepts the next incoming call and returns the new
// connection and the remote address.

この記述は、あたかもAcceptTCP関数が*TCPConnとリモートアドレスの2つの値を直接返すかのように読めてしまいます。しかし、実際の関数シグネチャは以下の通りです。

func (l *TCPListener) AcceptTCP() (*TCPConn, error)

このシグネチャが示すように、AcceptTCPは*TCPConn型のポインタとerror型の2つの値を返します。リモートアドレスは*TCPConnオブジェクトの内部にカプセル化されており、conn.RemoteAddr()メソッドを呼び出すことで取得できます。

この不一致を解消するため、コメントから「and the remote address.」という部分が削除されました。

// AcceptTCP accepts the next incoming call and returns the new
// connection.

これにより、ドキュメンテーションは関数の実際の戻り値と完全に一致し、開発者がAPIの振る舞いを正確に理解できるようになります。同様の修正がAcceptUnix関数にも適用されています。

この修正は、Go言語のドキュメンテーションの品質と正確性を維持するための継続的な取り組みの一環です。

参考にした情報源リンク

Go言語のソースコード (GitHub): https://github.com/golang/go
Go言語のコードレビューシステム (Gerrit): https://go.dev/cl/13592043 (コミットメッセージに記載されているCLリンク)
一般的なネットワークプログラミングにおけるacceptシステムコール: https://man7.org/linux/man-pages/man2/accept.2.html (Linux man page for accept)
Go言語のクロスプラットフォーム開発に関する情報

comemo