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

このコミットは、Go言語の標準ライブラリ全体にわたるドキュメンテーションの慣用的な表現を改善することを目的としています。特に、ブーリアン値を返す関数のコメントにおいて、「returns whether」という表現を「reports whether」に統一する変更が行われました。

コミット

commit abe384f68a8572e94acea0f3966cc72cbedd9c29
Author: Rob Pike <r@golang.org>
Date:   Tue Jul 23 11:59:49 2013 +1000

    all: be more idiomatic when documenting boolean return values.
    Phrases like "returns whether or not the image is opaque" could be
    describing what the function does (it always returns, regardless of
    the opacity) or what it returns (a boolean indicating the opacity).
    Even when the "or not" is missing, the phrasing is bizarre.
    
    Go with "reports whether", which is still clunky but at least makes
    it clear we're talking about the return value.
    
    These were edited by hand. A few were cleaned up in other ways.
    
    R=golang-dev, dsymonds
    CC=golang-dev
    https://golang.org/cl/11699043

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

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

元コミット内容

all: be more idiomatic when documenting boolean return values.
Phrases like "returns whether or not the image is opaque" could be
describing what the function does (it always returns, regardless of
the opacity) or what it returns (a boolean indicating the opacity).
Even when the "or not" is missing, the phrasing is bizarre.

Go with "reports whether", which is still clunky but at least makes
it clear we're talking about the return value.

These were edited by hand. A few were cleaned up in other ways.

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/11699043

変更の背景

Go言語のドキュメンテーションにおいて、ブーリアン値を返す関数の説明に「returns whether」という表現が使われることがありました。しかし、この表現は曖昧さを生む可能性がありました。具体的には、「関数が何かを返すかどうか」を説明しているのか、それとも「関数が返すブーリアン値が何を示すのか」を説明しているのかが不明瞭でした。

例えば、「returns whether or not the image is opaque」というフレーズは、関数が常に値を返すという事実を述べているのか、それとも返されるブーリアン値が画像の不透明度を示すのか、どちらとも解釈できてしまいます。このような曖昧さを解消し、ドキュメンテーションの意図をより明確にするために、Rob Pike氏によって「reports whether」という表現への統一が提案され、このコミットで適用されました。

この変更は、Go言語のドキュメンテーション全体の一貫性と明確性を高めるための、継続的な取り組みの一環です。

前提知識の解説

• Go言語のドキュメンテーション規約: Go言語には、godocツールによって自動生成されるドキュメンテーションのための特定の規約が存在します。関数や型のコメントは、その要素の動作や目的を明確に記述する必要があります。
• ブーリアン型: bool型は、trueまたはfalseのいずれかの値を取るデータ型です。Go言語では、条件分岐や真偽判定に広く用いられます。
• 慣用的な表現 (Idiomatic Expression): 特定のプログラミング言語やコミュニティにおいて、自然で推奨されるコーディングスタイルや表現方法を指します。Go言語では、シンプルさ、明確さ、効率性が重視されます。
• godoc: Go言語のソースコードからドキュメンテーションを生成するツールです。コメントの品質は、godocによって生成されるドキュメントの品質に直結します。

技術的詳細

このコミットの技術的な変更は、主にGo言語のソースコード内のコメント文字列の置換です。具体的には、ブーリアン値を返す関数のドキュメンテーションコメントにおいて、以下のパターンで変更が行われました。

• // ... returns whether ...
• // ... returns whether or not ...

これらのコメントが、

• // ... reports whether ...

という形式に統一されました。

「reports whether」という表現は、「〜かどうかを報告する」という意味合いが強く、関数がブーリアン値を返すこと、そしてそのブーリアン値が特定の条件の真偽を示すことをより明確に伝えます。これにより、読者は関数の戻り値が何を表しているのかを直感的に理解できるようになります。

この変更は、Go言語の標準ライブラリの広範なファイルに手作業で適用されました。これは、単なる文字列置換ではなく、各コメントの文脈を考慮し、必要に応じて他の表現の修正も伴ったことを示唆しています。

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

このコミットは、特定の機能の追加やバグ修正ではなく、Go言語の標準ライブラリ全体にわたるドキュメンテーションコメントの修正です。そのため、特定の「コアとなるコード」というよりは、多数のファイルのドキュメンテーションコメントが変更されています。

変更されたファイルの一部を以下に示します。

• doc/play/life.go
• src/cmd/dist/plan9.c
• src/cmd/dist/unix.c
• src/cmd/dist/windows.c
• src/cmd/gc/export.c
• src/cmd/gc/subr.c
• src/cmd/go/pkg.go
• src/pkg/bufio/scan.go
• src/pkg/bytes/bytes.go
• src/pkg/crypto/ecdsa/ecdsa.go
• src/pkg/crypto/x509/pkix/pkix.go
• src/pkg/debug/gosym/symtab.go
• src/pkg/encoding/asn1/asn1.go
• src/pkg/encoding/gob/encode.go
• src/pkg/encoding/json/tags.go
• src/pkg/flag/flag.go
• src/pkg/fmt/print.go
• src/pkg/go/ast/ast.go
• src/pkg/go/doc/testdata/testing.0.golden
• src/pkg/go/doc/testdata/testing.1.golden
• src/pkg/go/doc/testdata/testing.2.golden
• src/pkg/go/doc/testdata/testing.go
• src/pkg/html/template/context.go
• src/pkg/html/template/css.go
• src/pkg/html/template/escape.go
• src/pkg/html/template/js.go
• src/pkg/html/template/transition.go
• src/pkg/image/format.go
• src/pkg/image/geom.go
• src/pkg/image/image.go
• src/pkg/image/jpeg/dct_test.go
• src/pkg/image/names.go
• src/pkg/math/bits.go
• src/pkg/mime/multipart/multipart.go
• src/pkg/net/http/cookiejar/jar.go
• src/pkg/net/http/header.go
• src/pkg/net/http/request.go
• src/pkg/net/http/response.go
• src/pkg/net/http/server.go
• src/pkg/net/http/transfer.go
• src/pkg/os/doc.go
• src/pkg/os/error.go
• src/pkg/regexp/regexp.go
• src/pkg/sort/sort.go
• src/pkg/text/template/exec.go

これらのファイルにおいて、ブーリアン値を返す関数のドキュメンテーションコメントが修正されています。

コアとなるコードの解説

このコミットは、コードのロジック自体を変更するものではなく、主にドキュメンテーションコメントのテキストを変更するものです。したがって、特定の「コアとなるコード」の動作を解説するものではありません。

しかし、変更されたコメントの例をいくつか挙げることで、変更の意図をより具体的に理解できます。

例1: doc/play/life.go

--- a/doc/play/life.go
+++ b/doc/play/life.go
@@ -28,7 +28,7 @@ func (f *Field) Set(x, y int, b bool) {
 	f.s[y][x] = b
 }
 
-// Alive returns whether the specified cell is alive.
+// Alive reports whether the specified cell is alive.
 // If the x or y coordinates are outside the field boundaries they are wrapped
 // toroidally. For instance, an x value of -1 is treated as width-1.
 func (f *Field) Alive(x, y int) bool {

Alive関数は、指定されたセルが生きているかどうかをブーリアン値で返します。変更前は「returns whether」でしたが、変更後は「reports whether」となり、戻り値がセルの状態を「報告する」というニュアンスが強調されています。

例2: src/pkg/bytes/bytes.go

--- a/src/pkg/bytes/bytes.go
+++ b/src/pkg/bytes/bytes.go
@@ -77,7 +77,7 @@ func Count(s, sep []byte) int {
 	return count
 }
 
-// Contains returns whether subslice is within b.
+// Contains reports whether subslice is within b.
 func Contains(b, subslice []byte) bool {
 	return Index(b, subslice) != -1
 }

Contains関数は、バイトスライスbがsubsliceを含むかどうかをブーリアン値で返します。ここでも「returns whether」から「reports whether」に変更され、関数の目的がより明確に伝わるようになっています。

これらの変更は、Go言語のドキュメンテーション全体で一貫した、より明確な表現を確立するためのものです。

関連リンク

• Go言語のドキュメンテーション規約: Go言語の公式ドキュメンテーションには、コメントの書き方に関するガイドラインが含まれています。
  • Effective Go - Documentation
• Go Code Review Comments: Goのコードレビューでよく指摘される点や、推奨されるスタイルに関するドキュメント。
  • Go Code Review Comments - Doc comments

参考にした情報源リンク

• コミットのChange-ID: https://golang.org/cl/11699043 (これはコミットメッセージに記載されているGoのコードレビューシステムGerritのリンクです。現在はGitHubにリダイレクトされます。)
• Go言語の公式ドキュメンテーション: Go言語の標準ライブラリのドキュメンテーションは、このコミットによって改善されたコメントに基づいて生成されています。
  • Go Packages Documentation
• Go言語のGitHubリポジトリ:
  • golang/go on GitHub
• Rob PikeのGoに関する記事や講演: Rob PikeはGo言語の共同開発者の一人であり、彼のGoに関する見解やスタイルに関する情報は、このコミットの背景を理解する上で参考になります。
  • Rob Pike's website (彼のブログや記事へのリンクがある場合があります)
  • Go at Google: Language Design in the Service of Software Engineering (Go言語の設計原則に関する講演スライド)# [インデックス 16847] ファイルの概要

このコミットは、Go言語の標準ライブラリ全体にわたるドキュメンテーションの慣用的な表現を改善することを目的としています。特に、ブーリアン値を返す関数のコメントにおいて、「returns whether」という表現を「reports whether」に統一する変更が行われました。

コミット

commit abe384f68a8572e94acea0f3966cc72cbedd9c29
Author: Rob Pike <r@golang.org>
Date:   Tue Jul 23 11:59:49 2013 +1000

    all: be more idiomatic when documenting boolean return values.
    Phrases like "returns whether or not the image is opaque" could be
    describing what the function does (it always returns, regardless of
    the opacity) or what it returns (a boolean indicating the opacity).
    Even when the "or not" is missing, the phrasing is bizarre.
    
    Go with "reports whether", which is still clunky but at least makes
    it clear we're talking about the return value.
    
    These were edited by hand. A few were cleaned up in other ways.
    
    R=golang-dev, dsymonds
    CC=golang-dev
    https://golang.org/cl/11699043

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

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

元コミット内容

all: be more idiomatic when documenting boolean return values.
Phrases like "returns whether or not the image is opaque" could be
describing what the function does (it always returns, regardless of
the opacity) or what it returns (a boolean indicating the opacity).
Even when the "or not" is missing, the phrasing is bizarre.

Go with "reports whether", which is still clunky but at least makes
it clear we're talking about the return value.

These were edited by hand. A few were cleaned up in other ways.

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/11699043

変更の背景

Go言語のドキュメンテーションにおいて、ブーリアン値を返す関数の説明に「returns whether」という表現が使われることがありました。しかし、この表現は曖昧さを生む可能性がありました。具体的には、「関数が何かを返すかどうか」を説明しているのか、それとも「関数が返すブーリアン値が何を示すのか」を説明しているのかが不明瞭でした。

例えば、「returns whether or not the image is opaque」というフレーズは、関数が常に値を返すという事実を述べているのか、それとも返されるブーリアン値が画像の不透明度を示すのか、どちらとも解釈できてしまいます。このような曖昧さを解消し、ドキュメンテーションの意図をより明確にするために、Rob Pike氏によって「reports whether」という表現への統一が提案され、このコミットで適用されました。

この変更は、Go言語のドキュメンテーション全体の一貫性と明確性を高めるための、継続的な取り組みの一環です。

前提知識の解説

• Go言語のドキュメンテーション規約: Go言語には、godocツールによって自動生成されるドキュメンテーションのための特定の規約が存在します。関数や型のコメントは、その要素の動作や目的を明確に記述する必要があります。
• ブーリアン型: bool型は、trueまたはfalseのいずれかの値を取るデータ型です。Go言語では、条件分岐や真偽判定に広く用いられます。
• 慣用的な表現 (Idiomatic Expression): 特定のプログラミング言語やコミュニティにおいて、自然で推奨されるコーディングスタイルや表現方法を指します。Go言語では、シンプルさ、明確さ、効率性が重視されます。
• godoc: Go言語のソースコードからドキュメンテーションを生成するツールです。コメントの品質は、godocによって生成されるドキュメントの品質に直結します。

技術的詳細

このコミットの技術的な変更は、主にGo言語のソースコード内のコメント文字列の置換です。具体的には、ブーリアン値を返す関数のドキュメンテーションコメントにおいて、以下のパターンで変更が行われました。

• // ... returns whether ...
• // ... returns whether or not ...

これらのコメントが、

• // ... reports whether ...

という形式に統一されました。

「reports whether」という表現は、「〜かどうかを報告する」という意味合いが強く、関数がブーリアン値を返すこと、そしてそのブーリアン値が特定の条件の真偽を示すことをより明確に伝えます。これにより、読者は関数の戻り値が何を表しているのかを直感的に理解できるようになります。

この変更は、Go言語の標準ライブラリの広範なファイルに手作業で適用されました。これは、単なる文字列置換ではなく、各コメントの文脈を考慮し、必要に応じて他の表現の修正も伴ったことを示唆しています。

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

このコミットは、特定の機能の追加やバグ修正ではなく、Go言語の標準ライブラリ全体にわたるドキュメンテーションコメントの修正です。そのため、特定の「コアとなるコード」というよりは、多数のファイルのドキュメンテーションコメントが変更されています。

変更されたファイルの一部を以下に示します。

• doc/play/life.go
• src/cmd/dist/plan9.c
• src/cmd/dist/unix.c
• src/cmd/dist/windows.c
• src/cmd/gc/export.c
• src/cmd/gc/subr.c
• src/cmd/go/pkg.go
• src/pkg/bufio/scan.go
• src/pkg/bytes/bytes.go
• src/pkg/crypto/ecdsa/ecdsa.go
• src/pkg/crypto/x509/pkix/pkix.go
• src/pkg/debug/gosym/symtab.go
• src/pkg/encoding/asn1/asn1.go
• src/pkg/encoding/gob/encode.go
• src/pkg/encoding/json/tags.go
• src/pkg/flag/flag.go
• src/pkg/fmt/print.go
• src/pkg/go/ast/ast.go
• src/pkg/go/doc/testdata/testing.0.golden
• src/pkg/go/doc/testdata/testing.1.golden
• src/pkg/go/doc/testdata/testing.2.golden
• src/pkg/go/doc/testdata/testing.go
• src/pkg/html/template/context.go
• src/pkg/html/template/css.go
• src/pkg/html/template/escape.go
• src/pkg/html/template/js.go
• src/pkg/html/template/transition.go
• src/pkg/image/format.go
• src/pkg/image/geom.go
• src/pkg/image/image.go
• src/pkg/image/jpeg/dct_test.go
• src/pkg/image/names.go
• src/pkg/math/bits.go
• src/pkg/mime/multipart/multipart.go
• src/pkg/net/http/cookiejar/jar.go
• src/pkg/net/http/header.go
• src/pkg/net/http/request.go
• src/pkg/net/http/response.go
• src/pkg/net/http/server.go
• src/pkg/net/http/transfer.go
• src/pkg/os/doc.go
• src/pkg/os/error.go
• src/pkg/regexp/regexp.go
• src/pkg/sort/sort.go
• src/pkg/text/template/exec.go

これらのファイルにおいて、ブーリアン値を返す関数のドキュメンテーションコメントが修正されています。

コアとなるコードの解説

このコミットは、コードのロジック自体を変更するものではなく、主にドキュメンテーションコメントのテキストを変更するものです。したがって、特定の「コアとなるコード」の動作を解説するものではありません。

しかし、変更されたコメントの例をいくつか挙げることで、変更の意図をより具体的に理解できます。

例1: doc/play/life.go

--- a/doc/play/life.go
+++ b/doc/play/life.go
@@ -28,7 +28,7 @@ func (f *Field) Set(x, y int, b bool) {
 	f.s[y][x] = b
 }
 
-// Alive returns whether the specified cell is alive.
+// Alive reports whether the specified cell is alive.
 // If the x or y coordinates are outside the field boundaries they are wrapped
 // toroidally. For instance, an x value of -1 is treated as width-1.
 func (f *Field) Alive(x, y int) bool {

Alive関数は、指定されたセルが生きているかどうかをブーリアン値で返します。変更前は「returns whether」でしたが、変更後は「reports whether」となり、戻り値がセルの状態を「報告する」というニュアンスが強調されています。

例2: src/pkg/bytes/bytes.go

--- a/src/pkg/bytes/bytes.go
+++ b/src/pkg/bytes/bytes.go
@@ -77,7 +77,7 @@ func Count(s, sep []byte) int {
 	return count
 }
 
-// Contains returns whether subslice is within b.
+// Contains reports whether subslice is within b.
 func Contains(b, subslice []byte) bool {
 	return Index(b, subslice) != -1
 }

Contains関数は、バイトスライスbがsubsliceを含むかどうかをブーリアン値で返します。ここでも「returns whether」から「reports whether」に変更され、関数の目的がより明確に伝わるようになっています。

これらの変更は、Go言語のドキュメンテーション全体で一貫した、より明確な表現を確立するためのものです。

関連リンク

• Go言語のドキュメンテーション規約: Go言語の公式ドキュメンテーションには、コメントの書き方に関するガイドラインが含まれています。
  • Effective Go - Documentation
• Go Code Review Comments: Goのコードレビューでよく指摘される点や、推奨されるスタイルに関するドキュメント。
  • Go Code Review Comments - Doc comments

参考にした情報源リンク

• コミットのChange-ID: https://golang.org/cl/11699043 (これはコミットメッセージに記載されているGoのコードレビューシステムGerritのリンクです。現在はGitHubにリダイレクトされます。)
• Go言語の公式ドキュメンテーション: Go言語の標準ライブラリのドキュメンテーションは、このコミットによって改善されたコメントに基づいて生成されています。
  • Go Packages Documentation
• Go言語のGitHubリポジトリ:
  • golang/go on GitHub
• Rob PikeのGoに関する記事や講演: Rob PikeはGo言語の共同開発者の一人であり、彼のGoに関する見解やスタイルに関する情報は、このコミットの背景を理解する上で参考になります。
  • Rob Pike's website (彼のブログや記事へのリンクがある場合があります)
  • Go at Google: Language Design in the Service of Software Engineering (Go言語の設計原則に関する講演スライド)
• Web検索結果: Go言語におけるブーリアン戻り値のドキュメンテーションに関する慣用的な表現についての情報。
  • golang.org (https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQG0_sGed0sToMSgnd9FwEYocKZ04I7JIagW4ljWQRKJ8IfTS3aLwx4dcGTb6OHx2iB4KeaT0RFU1t6VGUNc8kFlu6OLwzlzrZJHtJ08TFgREcR_HmKLcO-tXQqRt8c=)