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

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

このコミットは、Go言語の標準ライブラリの一部である src/pkg/builtin/builtin.go ファイルに対する変更です。具体的には、Go言語に組み込み関数として存在する print および println のドキュメンテーションを追加しています。

コミット

commit c7065e927d1e8bbee6365bc8acfdf0b58ffdce8a
Author: Robert Griesemer <gri@golang.org>
Date:   Tue Jul 9 16:20:19 2013 -0700

    builtin: document print and println
    
    Fixes #5787.
    
    R=r
    CC=golang-dev
    https://golang.org/cl/11057043

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

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

元コミット内容

builtin: document print and println

Fixes #5787.

R=r
CC=golang-dev
https://golang.org/cl/11057043

変更の背景

このコミットの背景には、Go言語の組み込み関数である print と println が、その存在意義や使用上の注意点について公式なドキュメンテーションが不足していたという問題があります。コミットメッセージにある Fixes #5787 は、この変更がGoのIssue 5787を解決するものであることを示しています。

Go言語における print と println は、一般的なプログラミング言語の標準出力関数とは異なり、主にブートストラップ（言語の初期開発段階）やデバッグ目的で使用されることが意図されています。これらの関数は、Go言語の仕様書には明記されておらず、将来的に言語から削除される可能性も示唆されていました。しかし、ドキュメンテーションが不足していたため、開発者がこれらの関数の特性や推奨される使用方法を理解するのが困難でした。

このコミットは、これらの関数の役割、出力先（標準エラー出力）、フォーマットの特性、そして「ブートストラップとデバッグに有用であり、言語に残り続ける保証はない」という重要な注意点を明確にすることで、開発者の混乱を解消し、適切な使用を促すことを目的としています。

前提知識の解説

このコミットを理解するためには、以下のGo言語に関する前提知識が必要です。

  • Go言語の組み込み関数 (Built-in Functions): Go言語には、len, cap, make, new, panic, recover など、言語仕様に直接組み込まれている特別な関数群があります。これらは import なしで利用でき、コンパイラによって特別に扱われます。print と println もこの組み込み関数の一部です。
  • src/pkg/builtin/builtin.go: このファイルは、Go言語のコンパイラが認識する組み込み関数や型（error インターフェースなど）の宣言が含まれています。これらの宣言は、Goのソースコード内でこれらの組み込み要素がどのように見えるかを定義していますが、実際の動作はコンパイラやランタイムによって実装されます。
  • 標準出力と標準エラー出力: 多くのプログラミング言語と同様に、Go言語もプログラムの出力を扱うための標準的なストリームを提供します。
    • 標準出力 (stdout): 通常のプログラム出力が送られる場所です。Goでは fmt パッケージの fmt.Print, fmt.Println, fmt.Printf などがこれに該当します。
    • 標準エラー出力 (stderr): エラーメッセージや診断情報が送られる場所です。print と println は、この標準エラー出力に書き込みます。これは、通常のプログラム出力とデバッグ出力を分離するための一般的な慣習です。
  • Go言語のドキュメンテーション: Go言語では、コード内のコメントを特定の形式で記述することで、自動的にドキュメンテーションを生成するツール (go doc) が提供されています。関数や型の宣言の直前に記述されたコメントは、その要素のドキュメンテーションとして扱われます。
  • Go言語の進化と安定性: Go言語は、その初期段階から安定した言語仕様を目指していますが、特に初期のバージョンでは、一部の機能（特にブートストラップやデバッグ目的の機能）が将来的に変更または削除される可能性がありました。print と println は、まさにそのようなカテゴリに属する関数でした。

技術的詳細

このコミットの技術的な詳細は、Go言語の組み込み関数のドキュメンテーション方法と、print/println の具体的な動作特性に焦点を当てています。

  1. ドキュメンテーションの追加: Go言語では、関数や変数、型などの宣言の直前に記述されたコメントが、その要素の公式ドキュメンテーションとして認識されます。このコミットでは、builtin.go 内の print および println 関数の宣言の直前に、複数行のコメントを追加しています。これらのコメントは go doc コマンドによって抽出され、開発者がこれらの関数の情報を参照する際に利用されます。

  2. print と println の特性の明記: 追加されたドキュメンテーションは、以下の重要な特性を明確にしています。

    • 出力先: 「標準エラー出力に結果を書き込む (writes the result to standard error)」。これは、通常の fmt.Print などが標準出力に書き込むのとは異なる重要な点です。
    • フォーマット: 「実装固有の方法で引数をフォーマットする (formats its arguments in an implementation-specific way)」。これは、fmt パッケージのように厳密なフォーマット規則がないことを意味し、Goのバージョンやコンパイラの実装によって出力形式が変わる可能性があることを示唆しています。
    • println の追加特性: println については、「引数間に常にスペースが追加され、改行が追加される (Spaces are always added between arguments and a newline is appended.)」と明記されています。これは fmt.Println と同様の挙動ですが、print との差別化を図っています。
    • 使用目的と将来の保証: 「ブートストラップとデバッグに有用であり、言語に残り続ける保証はない (useful for bootstrapping and debugging; it is not guaranteed to stay in the language.)」。これは、これらの関数がGo言語の安定したAPIの一部ではないことを強調し、本番コードでの使用を推奨しないというメッセージを伝えています。

  3. Type の使用: func print(args ...Type) および func println(args ...Type) のように、引数の型が Type と宣言されています。これは、builtin.go ファイルがコンパイラによって特別に扱われるため、実際のGoの型システムとは異なる「擬似的な型」として機能します。実際のGoコードでは、print や println は任意の型の引数を受け取ることができます（interface{} の可変長引数として扱われる）。この Type は、コンパイラがこれらの組み込み関数を認識するための内部的なプレースホルダーのようなものです。

このコミットは、コードの機能的な変更ではなく、既存の機能に対するドキュメンテーションの改善であり、Go言語のユーザビリティと理解度を向上させるための重要なステップです。

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

変更は src/pkg/builtin/builtin.go ファイルに集中しており、以下の13行が追加されています。

--- a/src/pkg/builtin/builtin.go
+++ b/src/pkg/builtin/builtin.go
@@ -236,6 +236,19 @@ func panic(v interface{})\
 // panicking.\
 func recover() interface{}\
 \
+// The print built-in function formats its arguments in an implementation-\
+// specific way and writes the result to standard error.\
+// Print is useful for bootstrapping and debugging; it is not guaranteed\
+// to stay in the language.\
+func print(args ...Type)\
+\
+// The println built-in function formats its arguments in an implementation-\
+// specific way and writes the result to standard error.\
+// Spaces are always added between arguments and a newline is appended.\
+// Println is useful for bootstrapping and debugging; it is not guaranteed\
+// to stay in the language.\
+func println(args ...Type)\
+\
 // The error built-in interface type is the conventional interface for\
 // representing an error condition, with the nil value representing no error.\
 type error interface {

コアとなるコードの解説

追加されたコードは、print と println 関数の宣言と、それらに付随するドキュメンテーションコメントです。

  • func print(args ...Type): これは print 関数の宣言です。args ...Type は、この関数が任意の数の引数を受け取ることができる可変長引数であることを示しています。前述の通り、Type はコンパイラが内部的に使用するプレースホルダーであり、実際のGoコードでは任意の型が渡されます。

  • // The print built-in function formats its arguments in an implementation-\n// specific way and writes the result to standard error.\n// Print is useful for bootstrapping and debugging; it is not guaranteed\n// to stay in the language.: これが print 関数に対するドキュメンテーションコメントです。

    • 1行目と2行目: print 関数が引数を「実装固有の方法でフォーマット」し、「標準エラー出力に書き込む」ことを説明しています。
    • 3行目と4行目: print が「ブートストラップとデバッグに有用」であり、「言語に残り続ける保証はない」という重要な注意点を述べています。

  • func println(args ...Type): これは println 関数の宣言で、print と同様に可変長引数を受け取ります。

  • // The println built-in function formats its arguments in an implementation-\n// specific way and writes the result to standard error.\n// Spaces are always added between arguments and a newline is appended.\n// Println is useful for bootstrapping and debugging; it is not guaranteed\n// to stay in the language.: これが println 関数に対するドキュメンテーションコメントです。

    • 1行目と2行目: print と同様に、引数を「実装固有の方法でフォーマット」し、「標準エラー出力に書き込む」ことを説明しています。
    • 3行目: println の特徴として、「引数間に常にスペースが追加され、改行が追加される」ことを明記しています。
    • 4行目と5行目: print と同様に、「ブートストラップとデバッグに有用」であり、「言語に残り続ける保証はない」という注意点を述べています。

これらの追加により、Go言語の公式ドキュメンテーションツールを通じて、print と println の正確な挙動と意図された使用方法が開発者に提供されるようになりました。

関連リンク

  • Go言語の組み込み関数に関する公式ドキュメンテーション (このコミットによって追加された内容が反映されています):
    • go doc builtin.print
    • go doc builtin.println
  • Go言語の fmt パッケージのドキュメンテーション (標準的な出力関数):
  • Go言語のIssueトラッカー (Issue 5787の詳細は、Goの公式Issueトラッカーで確認できますが、古いIssueはアーカイブされている場合があります):

参考にした情報源リンク

  • Go言語の公式リポジトリ: https://github.com/golang/go
  • Go言語のコードレビューシステム (Gerrit): https://golang.org/cl/11057043 (このコミットのGerritレビューページ)
  • Go言語のドキュメンテーションツール go doc の使い方に関する情報源。
  • Go言語の仕様書 (The Go Programming Language Specification): https://go.dev/ref/spec (print と println は仕様書には含まれていませんが、Go言語の全体像を理解する上で重要です。)
  • Go言語の builtin パッケージのソースコード: https://github.com/golang/go/blob/master/src/builtin/builtin.go (現在の最新版のファイル)
  • Go言語のIssue 5787: https://github.com/golang/go/issues/5787 (このIssueは、print と println のドキュメンテーションの必要性について議論されたものです。)
  • Go言語の print と println に関する議論やブログ記事 (Go言語の歴史的経緯や設計思想を理解する上で役立ちます)。