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

このコミットは、Go言語の標準ライブラリにおける公開ドキュメントの記述スタイルを統一することを目的としています。具体的には、ブール値を返す関数の説明で用いられていた「true iff」（if and only if の略）という表現を「whether」に置き換える変更が行われています。これにより、Goのドキュメント全体でより一貫性のある、分かりやすい表現が採用されます。

コミット

• コミットハッシュ: 48b9be2b1994d4f9109294102df271c339dc9897
• Author: Brad Fitzpatrick bradfitz@golang.org
• Date: Mon Jul 22 16:20:30 2013 -0700

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

https://github.com/golang/go/commit/48b9be2b1994d4f9109294102df271c339dc9897

元コミット内容

all: change "true iff" to "whether" in public docs

For consistency with Go documentation style.

R=golang-dev, khr
CC=golang-dev
https://golang.org/cl/11697043

変更の背景

この変更の背景には、Go言語の公式ドキュメントにおける記述スタイルの一貫性を高めるという明確な意図があります。Go言語は、その設計思想において「シンプルさ」と「明瞭さ」を重視しており、これはコードだけでなく、ドキュメントにも適用されます。

「true iff」という表現は、数学や論理学の分野で「必要十分条件」を示す際に用いられる厳密な表現ですが、一般的なプログラミングドキュメントにおいては、やや専門的で堅苦しい印象を与える可能性があります。また、英語を母国語としない開発者にとっては、その意味を即座に理解するのが難しい場合もあります。

Go言語のドキュメントは、誰にとっても読みやすく、理解しやすいことを目指しています。そのため、ブール値を返す関数の説明において、より自然で平易な「whether」（〜かどうか）という表現に統一することで、ドキュメント全体の可読性とアクセシビリティを向上させることが目的とされました。これは、Go言語がコミュニティ全体で共有する「Goらしい」スタイルガイドラインの一部として、ドキュメントの品質を継続的に改善する取り組みの一環です。

前提知識の解説

「true iff」とは

「true iff」は、「if and only if」（〜の場合に限り、かつその場合にのみ）の略語で、主に数学、論理学、コンピュータサイエンスの理論分野で用いられる厳密な表現です。これは、ある命題が真であるための必要十分条件を示す際に使用されます。

例えば、「A is true iff B is true」という表現は、「Aが真であることとBが真であることは同値である」という意味になります。つまり、Bが真であればAは必ず真であり、Aが真であればBは必ず真である、という双方向の含意関係を示します。

プログラミングの文脈では、ある関数がtrueを返す条件が、特定の入力や状態に厳密に依存する場合にこの表現が使われることがあります。しかし、その厳密さゆえに、一般的なドキュメントでは読みにくさを感じる人もいます。

Go言語のドキュメントスタイル

Go言語は、その設計思想として「シンプルさ」「明瞭さ」「実用性」を重視しており、これはコードの書き方だけでなく、ドキュメントの書き方にも反映されています。Goのドキュメントは、簡潔で直接的であり、曖昧さを避ける傾向があります。

公式のGoドキュメントや標準ライブラリのコメントでは、以下のような特徴が見られます。

• 簡潔性: 不要な言葉を省き、要点を明確に伝える。
• 直接性: 遠回しな表現を避け、直接的に機能や振る舞いを説明する。
• 一貫性: 用語や表現方法を統一し、読者が混乱しないようにする。
• 実用性: 読者がコードを理解し、効果的に使用できるように、具体的な情報を提供する。

このコミットは、まさにこの「一貫性」と「明瞭さ」というGoのドキュメントスタイルの原則に則ったものです。「true iff」のような専門的な表現を、より一般的な「whether」に置き換えることで、より多くの開発者にとって理解しやすいドキュメントを目指しています。

技術的詳細

このコミットは、Go言語のソースコード内のコメント、特に公開APIのドキュメントコメント（GoDocコメント）における特定のフレーズの置換に焦点を当てています。技術的な変更は、コードの振る舞い自体には一切影響を与えません。これは純粋にドキュメンテーションの改善であり、コードのロジックやパフォーマンス、セキュリティには影響しません。

変更の対象となったのは、ブール値を返す関数の説明文です。例えば、func Verify(...) bool のような関数は、検証が成功したか失敗したかをtrueまたはfalseで返します。以前のドキュメントでは、このtrueを返す条件を「returns true iff ...」と記述していました。このコミットでは、この表現を「returns whether ...」に統一しています。

この変更は、Go言語のドキュメントツール（go docコマンドやpkg.go.devなど）によって生成されるドキュメントの表示に影響を与えます。これらのツールはソースコード内のコメントを解析し、開発者向けのドキュメントを生成するため、コメント内の表現の変更は直接的に公開ドキュメントの変更につながります。

具体的に変更されたファイルは、crypto/ecdsa、crypto/x509/pkix、encoding/asn1の3つです。これらはいずれもGoの標準ライブラリの一部であり、暗号化、証明書管理、データエンコーディングといった基盤的な機能を提供しています。これらのパッケージのドキュメントは、多くの開発者が参照するため、表現の統一はGoエコシステム全体のユーザビリティ向上に寄与します。

この種のドキュメンテーションの変更は、ソフトウェア開発において非常に重要です。なぜなら、高品質なドキュメントは、コードの理解を深め、誤用を防ぎ、新しい開発者のオンボーディングを容易にするからです。特に、Goのようにシンプルさを追求する言語では、ドキュメントの明瞭さが言語の使いやすさに直結します。

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

このコミットでは、以下の3つのファイルが変更されています。

1. src/pkg/crypto/ecdsa/ecdsa.go
2. src/pkg/crypto/x509/pkix/pkix.go
3. src/pkg/encoding/asn1/asn1.go

それぞれのファイルの変更内容は以下の通りです。

diff --git a/src/pkg/crypto/ecdsa/ecdsa.go b/src/pkg/crypto/ecdsa/ecdsa.go
index 2550002293..f642cb9ab7 100644
--- a/src/pkg/crypto/ecdsa/ecdsa.go
+++ b/src/pkg/crypto/ecdsa/ecdsa.go
@@ -124,7 +124,7 @@ func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err err
 }
 
 // Verify verifies the signature in r, s of hash using the public key, pub. It
-// returns true iff the signature is valid.
+// returns whether the signature is valid.
 func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool {
 	// See [NSA] 3.4.2
 	c := pub.Curve
diff --git a/src/pkg/crypto/x509/pkix/pkix.go b/src/pkg/crypto/x509/pkix/pkix.go
index 738659011f..2c600aee3a 100644
--- a/src/pkg/crypto/x509/pkix/pkix.go
+++ b/src/pkg/crypto/x509/pkix/pkix.go
@@ -144,7 +144,7 @@ type CertificateList struct {
 	SignatureValue     asn1.BitString
 }
 
-// HasExpired returns true iff now is past the expiry time of certList.
+// HasExpired returns whether now is past the expiry time of certList.
 func (certList *CertificateList) HasExpired(now time.Time) bool {
 	return now.After(certList.TBSCertList.NextUpdate)
 }
diff --git a/src/pkg/encoding/asn1/asn1.go b/src/pkg/encoding/asn1/asn1.go
index a9d17a3c14..c53430850d 100644
--- a/src/pkg/encoding/asn1/asn1.go
+++ b/src/pkg/encoding/asn1/asn1.go
@@ -183,7 +183,7 @@ func parseBitString(bytes []byte) (ret BitString, err error) {\n // An ObjectIdentifier represents an ASN.1 OBJECT IDENTIFIER.\n type ObjectIdentifier []int\n \n-// Equal returns true iff oi and other represent the same identifier.\n+// Equal returns whether oi and other represent the same identifier.\n func (oi ObjectIdentifier) Equal(other ObjectIdentifier) bool {\n 	if len(oi) != len(other) {\n 		return false

コアとなるコードの解説

このコミットによるコードの変更は、Go言語のドキュメントコメント内の特定のフレーズの置換のみです。実際のGoコードのロジックや動作には一切影響を与えません。

各変更箇所は、ブール値を返す関数のGoDocコメント（関数宣言の直前にあるコメントで、go docコマンドやpkg.go.devで表示されるドキュメントの元となるもの）を修正しています。

1. src/pkg/crypto/ecdsa/ecdsa.go の変更:

   • Verify 関数のドキュメントコメントが変更されました。
   • 変更前: // returns true iff the signature is valid.
   • 変更後: // returns whether the signature is valid.
   • Verify関数は、ECDSA署名が有効であるかどうかを検証し、その結果をブール値で返します。この変更により、「署名が有効である場合に限りtrueを返す」という厳密な表現から、「署名が有効であるかどうかを返す」というより自然な表現に変わりました。

2. src/pkg/crypto/x509/pkix/pkix.go の変更:

   • CertificateList 型の HasExpired メソッドのドキュメントコメントが変更されました。
   • 変更前: // HasExpired returns true iff now is past the expiry time of certList.
   • 変更後: // HasExpired returns whether now is past the expiry time of certList.
   • HasExpired メソッドは、証明書失効リスト（CRL）が現在時刻を過ぎて期限切れになっているかどうかをブール値で返します。この変更により、ドキュメントの表現が統一されました。

3. src/pkg/encoding/asn1/asn1.go の変更:

   • ObjectIdentifier 型の Equal メソッドのドキュメントコメントが変更されました。
   • 変更前: // Equal returns true iff oi and other represent the same identifier.
   • 変更後: // Equal returns whether oi and other represent the same identifier.
   • Equal メソッドは、2つのASN.1オブジェクト識別子（OID）が同じ識別子を表しているかどうかをブール値で返します。ここでも、ドキュメントの表現がGoのスタイルガイドラインに沿うように修正されました。

これらの変更は、Go言語のドキュメント全体で一貫した、より読みやすい表現を促進するための小さな、しかし重要なステップです。これにより、Goの標準ライブラリのAPIドキュメントが、より多くの開発者にとって理解しやすくなります。

関連リンク

• Go CL (Change List): https://golang.org/cl/11697043
  • これは、このコミットがGoのコードレビューシステム（Gerrit）上で提案された際の変更リストへのリンクです。Goの開発プロセスでは、すべての変更がこのようなCLとして提出され、レビューを経てマージされます。

参考にした情報源リンク

• Go言語公式ドキュメント: https://go.dev/doc/
  • Go言語のドキュメントスタイルや哲学について理解を深めるために参照しました。
• pkg.go.dev: https://pkg.go.dev/
  • Goの公開パッケージのドキュメントがどのように表示されるかを確認するために参照しました。
• Wikipedia - If and only if: https://en.wikipedia.org/wiki/If_and_only_if
  • 「iff」の厳密な意味と用法について確認するために参照しました。
• Go Code Review Comments: https://go.dev/wiki/CodeReviewComments
  • Goのコードレビューにおける一般的なコメントや推奨事項について、ドキュメンテーションに関する項目を参考にしました。