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

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

このコミットは、Go言語の標準ライブラリであるgo/formatパッケージ内のSource関数のドキュメンテーションを修正するものです。具体的には、Source関数の挙動に関する説明をより明確にし、特に部分的なソースコードのフォーマット時の挙動について誤解を招かないように改善しています。

コミット

go/format: fix documentation

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

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

元コミット内容

commit e95c41f30bef016c39f195c5a0e825c39f64f7fe
Author: Robert Griesemer <gri@golang.org>
Date:   Thu Mar 21 08:47:34 2013 -0700

    go/format: fix documentation
    
    R=r
    CC=golang-dev
    https://golang.org/cl/7920048

変更の背景

Go言語には、コードの自動フォーマットを行うためのgofmtツールが存在します。このツールは、Goのコードベース全体で一貫したコーディングスタイルを強制し、可読性を向上させることを目的としています。gofmtの機能は、go/formatという標準パッケージによって提供されており、開発者はこのパッケージを自身のGoプログラム内で利用して、Goソースコードのフォーマットを行うことができます。

このコミットの背景には、go/formatパッケージのSource関数のドキュメンテーションが、その実際の挙動を正確に反映していなかったという問題がありました。特に、部分的なGoソースコード（完全なファイルではなく、宣言やステートメントのリストなど）をフォーマットする際のインデントの適用方法や、インポートのソートに関する説明が不明瞭であったため、ユーザーが誤解する可能性がありました。このコミットは、そのドキュメンテーションの曖昧さを解消し、関数の正確な挙動を明確に伝えることを目的としています。

前提知識の解説

gofmtとgo/formatパッケージ

  • gofmt: gofmtはGo言語の公式なコードフォーマッタです。Goのインストールに同梱されており、Goのソースコードを自動的に整形し、Goコミュニティ全体で統一されたコーディングスタイルを強制します。これにより、コードの可読性が向上し、バージョン管理システムでの差分（diff）が意味のある変更のみに集中するようになります。gofmtは、インデント、アライメント、スペースなどをGoの公式レイアウトルールに従って調整します。
  • go/formatパッケージ: go/formatパッケージは、gofmtツールが内部で使用しているフォーマットロジックをGoプログラムから利用できるようにするライブラリです。このパッケージを使用することで、開発者は自身のアプリケーション内でGoソースコードのフォーマットをプログラム的に実行できます。例えば、エディタのプラグインやコード生成ツールなどで利用されます。
  • format.Source関数: go/formatパッケージの主要な関数の一つがSource関数です。この関数は、バイトスライスとして与えられたGoソースコードをgofmtの標準スタイルでフォーマットし、フォーマットされたバイトスライスを返します。また、I/Oエラーや構文エラーが発生した場合にはエラーを返します。

部分的なソースコードのフォーマット

format.Source関数は、完全なGoソースファイルだけでなく、Goの宣言やステートメントのリストのような部分的なソースコードもフォーマットできます。部分的なソースコードをフォーマットする場合、gofmtは元のソースコードの先頭と末尾の空白を結果に適用し、コードを含む最初の行のインデント量に合わせて結果をインデントします。重要な点として、部分的なソースコードの場合、インポートはソートされません。これは、完全なコンテキストがないため、インポートの依存関係を正確に解決できない可能性があるためです。

技術的詳細

このコミットは、src/pkg/go/format/format.goファイル内のSource関数のドキュメンテーションコメントを修正しています。変更の核心は、Source関数が部分的なソースコードを処理する際の挙動に関する説明の明確化です。

以前のドキュメンテーションでは、部分的なソースファイルの場合に「フォーマットされたsrcは、コードを含むsrcの最初の行と同じ量だけインデントされる」と記述されていました。この表現は、インデントがどのように適用されるかについて、やや曖昧な部分がありました。

新しいドキュメンテーションでは、この部分が「結果は、コードを含むsrcの最初の行と同じ量だけインデントされる」と修正されています。これにより、インデントがフォーマットされた結果全体に適用されることがより明確になります。

また、以前のドキュメンテーションでは、「Imports are not sorted for partial source files.」という文が、インデントに関する説明の後に続いていました。新しいドキュメンテーションでは、この文の前に「and the result is indented by the same amount as the first line of src containing code.」という句が追加され、文脈がより自然につながるようになっています。

これらの変更は、関数の挙動自体を変更するものではなく、その挙動をユーザーに正確に伝えるためのドキュメンテーションの改善に焦点を当てています。特に、部分的なソースコードのフォーマット時にインポートがソートされないという重要な制約が、より明確に伝わるようになっています。

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

--- a/src/pkg/go/format/format.go
+++ b/src/pkg/go/format/format.go
@@ -69,15 +69,14 @@ func Node(dst io.Writer, fset *token.FileSet, node interface{}) error {
 	return config.Fprint(dst, fset, node)
 }
 
-// Source formats src in canonical gofmt style and writes the result to dst
-// or returns an I/O or syntax error. src is expected to be a syntactically
+// Source formats src in canonical gofmt style and returns the result
+// or an (I/O or syntax) error. src is expected to be a syntactically
 // correct Go source file, or a list of Go declarations or statements.
 //
 // If src is a partial source file, the leading and trailing space of src
 // is applied to the result (such that it has the same leading and trailing
-// space as src), and the formatted src is indented by the same amount as
-// the first line of src containing code. Imports are not sorted for partial
-// source files.
+// space as src), and the result is indented by the same amount as the first
+// line of src containing code. Imports are not sorted for partial source files.
 //
 func Source(src []byte) ([]byte, error) {
 	fset := token.NewFileSet()

コアとなるコードの解説

上記のdiffを見ると、Source関数のドキュメンテーションコメントが変更されていることがわかります。

変更前:

// Source formats src in canonical gofmt style and writes the result to dst
// or returns an I/O or syntax error. src is expected to be a syntactically
// correct Go source file, or a list of Go declarations or statements.
//
// If src is a partial source file, the leading and trailing space of src
// is applied to the result (such that it has the same leading and trailing
// space as src), and the formatted src is indented by the same amount as
// the first line of src containing code. Imports are not sorted for partial
// source files.

変更後:

// Source formats src in canonical gofmt style and returns the result
// or an (I/O or syntax) error. src is expected to be a syntactically
// correct Go source file, or a list of Go declarations or statements.
//
// If src is a partial source file, the leading and trailing space of src
// is applied to the result (such that it has the same leading and trailing
// space as src), and the result is indented by the same amount as the first
// line of src containing code. Imports are not sorted for partial source files.

主な変更点は以下の通りです。

  1. 最初の行の修正:

    • 変更前: // Source formats src in canonical gofmt style and writes the result to dst
    • 変更後: // Source formats src in canonical gofmt style and returns the result
    • Source関数はio.Writerに結果を書き込むのではなく、バイトスライスとして結果を返します。この修正により、関数のシグネチャとドキュメンテーションが一致するようになりました。

  2. 部分的なソースファイルのインデントに関する説明の明確化:

    • 変更前: and the formatted src is indented by the same amount as the first line of src containing code.
    • 変更後: and the result is indented by the same amount as the first line of src containing code.
    • 「formatted src」から「result」に変更することで、インデントがフォーマットされた出力全体に適用されることがより明確になりました。

これらの変更は、Source関数の機能自体を変更するものではなく、その機能と挙動に関する説明をより正確で理解しやすいものにすることを目的としています。特に、部分的なGoコードを扱う際のインデントの挙動と、インポートがソートされないという重要な制約が、より明確にユーザーに伝わるようになりました。これにより、go/formatパッケージを利用する開発者が、関数の挙動を誤解することなく、より効果的に利用できるようになります。

関連リンク

参考にした情報源リンク