Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

このコミットは、Go言語の標準ライブラリであるunicodeパッケージ内のコメントの修正に関するものです。具体的には、*RangeTable型の変数に関するコメントの表現を、より汎用的で誤解を招かないように変更しています。この修正は、コードがウェブツールやコマンドラインツールで表示される際に、コメントと変数宣言の順序に関する誤解を避けることを目的としています。

コミット

commit 77f00e5e5ae39443174351ea514bbdf02ad59edd
Author: Russ Cox <rsc@golang.org>
Date:   Tue May 22 13:53:57 2012 -0400

    unicode: fix comment about variable types
    
    In both the web and command line tool,
    the comment is shown after the declaration.
    But in the code the comment is obviously before.
    Make the text not refer to a specific order.
    
    R=r, dsymonds
    CC=golang-dev
    https://golang.org/cl/6206094

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

https://github.com/golang/go/commit/77f00e5e5ae39443174351ea514bbdf02ad59edd

元コミット内容

unicode: fix comment about variable types

In both the web and command line tool,
the comment is shown after the declaration.
But in the code the comment is obviously before.
Make the text not refer to a specific order.

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

変更の背景

このコミットの背景には、Go言語のunicodeパッケージにおけるコメントの表示方法に関する微妙な問題がありました。

Go言語のunicodeパッケージには、Unicodeの文字プロパティやカテゴリを定義する多くの*RangeTable型の変数が含まれています。これらの変数群の前に、以下のようなコメントが付与されていました。

// The following variables are of type *RangeTable:

このコメントは、「以下の変数は*RangeTable型である」という意味合いで書かれています。しかし、コードがGitHubなどのウェブインターフェースや、特定のコマンドラインツールで表示される場合、コメントが変数宣言の「後」に表示されることがありました。一方で、実際のソースコード上では、コメントは変数宣言の「前」に位置しています。

この表示順序の不一致が、コメントの意図と実際の表示との間で混乱を招く可能性がありました。特に、コメントが「following (以下の)」という言葉を使っているため、コメントの後に変数宣言が続くという期待を生み出しますが、ツールによってはその期待が裏切られる形になっていました。

このコミットは、このような表示環境による差異を吸収し、コメントが常に正確な情報を提供するようにするために行われました。コメントの表現をより一般的なものにすることで、表示順序に依存しない記述に修正されています。

前提知識の解説

このコミットを理解するためには、以下の概念について知っておく必要があります。

  1. Unicode: Unicodeは、世界中のあらゆる文字をコンピュータで扱えるようにするための文字コードの国際標準です。各文字には一意のコードポイントが割り当てられ、文字のカテゴリ（例: 英字、数字、記号）、スクリプト（例: ラテン文字、アラビア文字）、プロパティ（例: 大文字、小文字、空白文字）などが定義されています。

  2. Go言語のunicodeパッケージ: Go言語の標準ライブラリであるunicodeパッケージは、Unicode標準で定義されている文字のプロパティやカテゴリに関する情報を提供します。これにより、Goプログラム内でUnicode文字の分類、変換、検証などを効率的に行うことができます。例えば、ある文字が数字であるか、空白文字であるか、あるいは特定のスクリプトに属するかなどを判定する関数やデータが提供されています。

  3. RangeTable型: unicodeパッケージの中心的なデータ構造の一つがRangeTable型です。これは、Unicodeのコードポイントの範囲（レンジ）を効率的に表現するための構造体です。特定の文字カテゴリ（例: Letter、Digit）やスクリプト（例: Cyrillic、Japanese）に属する文字の集合は、このRangeTableのインスタンスとして定義されます。これにより、あるコードポイントが特定の集合に含まれるかどうかを高速に判定できます。

  4. maketables.goとtables.go: Go言語のunicodeパッケージでは、tables.goというファイルがUnicodeの文字プロパティやカテゴリに関する膨大なデータを含んでいます。このtables.goファイルは手動で記述されているわけではなく、maketables.goという別のGoプログラムによって自動生成されます。 maketables.goは、Unicodeの公式データファイル（UnicodeData.txt、PropList.txtなど）を読み込み、それらをGoのコードとして表現し、tables.goに出力する役割を担っています。このため、tables.goに存在するコメントの一部は、maketables.goが出力する際に埋め込まれる形になっています。今回の修正は、このmaketables.goが出力するコメントの文字列自体を変更することで、最終的にtables.goに反映されるコメントを修正しています。

  5. コメントの役割と表示環境: プログラミングにおけるコメントは、コードの意図や動作を説明するために非常に重要です。しかし、コメントの表示方法は、使用するエディタ、IDE、バージョン管理システムのウェブインターフェース（例: GitHub）、ドキュメンテーション生成ツールなど、様々な環境によって異なります。このコミットは、そうした表示環境の違いによってコメントの意図が誤って伝わる可能性を考慮した、細やかな配慮がなされた修正と言えます。

技術的詳細

このコミットは、Go言語のunicodeパッケージにおけるコメントの文字列リテラルを変更するものです。技術的な変更点は非常にシンプルですが、その背景にある考慮事項は興味深いものです。

Goのunicodeパッケージは、Unicodeの文字プロパティを扱うための静的なデータテーブルを多数含んでいます。これらのテーブルは、*RangeTable型の変数として定義されており、例えばunicode.Letterやunicode.Digitなどがこれに該当します。

問題となっていたコメントは、これらの*RangeTable型の変数宣言の直前に配置されていました。元のコメントは以下の通りです。

// The following variables are of type *RangeTable:

このコメントは、その直後に続く変数群が*RangeTable型であることを示唆しています。しかし、Goのソースコードをそのまま表示する環境（例えば、テキストエディタやcatコマンド）では、コメントは変数宣言の「前」に表示されます。これは自然な配置です。

一方で、GitHubのコードビューや、特定のコードレビューツール、あるいはGoのドキュメンテーションツール（go docコマンドやgodocウェブサーバー）などでは、コメントとコードの表示順序が異なる場合があります。特に、変数宣言の前に書かれたコメントが、その変数宣言の「後」に表示されるようなレイアウトを採用しているツールも存在します。

このようなツールで表示された場合、元のコメントの「The following variables (以下の変数)」という表現は、コメントの「後に続く」変数ではなく、コメントの「前に表示されている」変数、あるいは「別の場所に定義されている」変数を指しているかのように誤解される可能性がありました。

このコミットでは、この曖昧さを解消するために、コメントの文字列を以下のように変更しました。

// These variables have type *RangeTable.

「The following variables (以下の変数)」を「These variables (これらの変数)」に変更することで、コメントが指し示す変数の位置関係に依存しない、より一般的な表現になりました。これにより、どのような表示環境においても、コメントが指す対象が明確になり、誤解が生じる可能性がなくなります。

この修正は、src/pkg/unicode/maketables.goとsrc/pkg/unicode/tables.goの2つのファイルに適用されています。

  • src/pkg/unicode/maketables.go: このファイルは、src/pkg/unicode/tables.goを生成するためのGoプログラムです。maketables.goがtables.goを生成する際に、このコメント文字列を埋め込むため、生成元であるmaketables.goの文字列リテラルも修正されています。
  • src/pkg/unicode/tables.go: このファイルは、maketables.goによって生成されるファイルであり、実際に*RangeTable型の変数宣言とそのコメントが含まれています。このファイルへの変更は、maketables.goの変更が反映された結果です。

このように、非常に小さなテキストの変更ですが、ユーザーインターフェースやドキュメンテーションの表示特性を考慮した、細やかな品質改善のコミットと言えます。

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

このコミットによるコードの変更は、以下の2つのファイルにおけるコメント文字列の修正です。

1. src/pkg/unicode/maketables.go

このファイルは、unicode/tables.goを生成するためのプログラムです。コメント文字列の出力部分が修正されています。

--- a/src/pkg/unicode/maketables.go
+++ b/src/pkg/unicode/maketables.go
@@ -488,7 +488,7 @@ func printCategories() {
 		func(code rune) bool { return chars[code].category == name })
 	}
 	decl.Sort()
-	fmt.Println("// The following variables are of type *RangeTable:")
+	fmt.Println("// These variables have type *RangeTable.")
 	fmt.Println("var (")
 	for _, d := range decl {
 		fmt.Print(d)
@@ -771,7 +771,7 @@ func printScriptOrProperty(doProps bool) {
 		fmt.Print("}\\n\\n")
 	}
 	decl.Sort()
-	fmt.Println("// The following variables are of type *RangeTable:")
+	fmt.Println("// These variables have type *RangeTable.")
 	fmt.Println("var (")
 	for _, d := range decl {
 		fmt.Print(d)

2. src/pkg/unicode/tables.go

このファイルは、maketables.goによって生成されるファイルであり、実際に*RangeTable型の変数宣言とそのコメントが含まれています。

--- a/src/pkg/unicode/tables.go
+++ b/src/pkg/unicode/tables.go
@@ -2701,7 +2701,7 @@ var _Zs = &RangeTable{
 	},
 }
 
-// The following variables are of type *RangeTable:
+// These variables have type *RangeTable.
 var (
 	Cc     = _Cc // Cc is the set of Unicode characters in category Cc.
 	Cf     = _Cf // Cf is the set of Unicode characters in category Cf.
@@ -4054,7 +4054,7 @@ var _Yi = &RangeTable{
 	},
 }
 
-// The following variables are of type *RangeTable:
+// These variables have type *RangeTable.
 var (
 	Arabic                 = _Arabic                 // Arabic is the set of Unicode characters in script Arabic.
 	Armenian               = _Armenian               // Armenian is the set of Unicode characters in script Armenian.
@@ -5116,7 +5116,7 @@ var _White_Space = &RangeTable{
 	},
 }
 
-// The following variables are of type *RangeTable:
+// These variables have type *RangeTable.
 var (
 	ASCII_Hex_Digit                    = _ASCII_Hex_Digit                    // ASCII_Hex_Digit is the set of Unicode characters with property ASCII_Hex_Digit.
 	Bidi_Control                       = _Bidi_Control                       // Bidi_Control is the set of Unicode characters with property Bidi_Control.

コアとなるコードの解説

このコミットのコアとなる変更は、Go言語のfmt.Println関数に渡される文字列リテラルの修正です。

src/pkg/unicode/maketables.goでは、printCategories()関数とprintScriptOrProperty()関数内で、*RangeTable型の変数宣言の前に挿入されるコメントを生成しています。

元のコードでは、以下の文字列を出力していました。 fmt.Println("// The following variables are of type *RangeTable:")

このコミットでは、この文字列を以下のように変更しています。 fmt.Println("// These variables have type *RangeTable.")

この変更により、maketables.goが生成するtables.goファイル内のコメントも自動的に更新されます。tables.goは、Goのunicodeパッケージが実際に使用するUnicodeデータテーブルの定義を含んでおり、その中に*RangeTable型の変数群が多数定義されています。

例えば、tables.go内のvar (ブロックの直前にあるコメントが、この修正によって変更されています。

変更前:

// The following variables are of type *RangeTable:
var (
	Cc     = _Cc // Cc is the set of Unicode characters in category Cc.
	// ...
)

変更後:

// These variables have type *RangeTable.
var (
	Cc     = _Cc // Cc is the set of Unicode characters in category Cc.
	// ...
)

この修正の目的は、前述の「変更の背景」と「技術的詳細」で述べた通り、コードの表示環境によってコメントと変数宣言の順序が異なる場合に、コメントの意図が誤って伝わることを防ぐためです。"The following variables"という表現は、コメントの物理的な位置に依存して「次に続く」という意味合いを持ちますが、"These variables"という表現は、コメントが指し示す対象（この場合はvar (ブロック内の変数群）をより直接的に指し、物理的な順序に依存しないため、より堅牢なコメントとなります。

これは、コードの機能には影響を与えない、純粋なドキュメンテーションとコードの可読性に関する改善です。

関連リンク

参考にした情報源リンク

  • Go言語の公式ドキュメント
  • GitHubのコミット履歴
  • Unicode Consortiumのウェブサイト (Unicode標準に関する情報)
  • Go言語のソースコード (特にsrc/pkg/unicodeディレクトリ)