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

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

このコミットは、Go 1リリースにおけるbinary.TotalSizeおよびbufio.NewReaderSize関数の変更に関するドキュメントの更新を目的としています。特に、これらの関数がGo 1で非推奨または変更され、古いコードがコンパイラによって検出されるようになったことを明記しています。これにより、開発者がGo 1への移行時にコードを更新する際の混乱を軽減し、コンパイラが変更を捕捉する役割を強調しています。

コミット

commit cf80ccd8f666a839466af874aefa0ee02c58efdc
Author: Rob Pike <r@golang.org>
Date:   Thu Feb 9 07:09:52 2012 +1100

    doc/go1: mention that the compiler catches TotalSize and NewReaderSize
    Today is Size day and the compiler will reject old code using these functions.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5644053

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

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

元コミット内容

doc/go1: mention that the compiler catches TotalSize and NewReaderSize
Today is Size day and the compiler will reject old code using these functions.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5644053

変更の背景

この変更は、Go言語のメジャーバージョンであるGo 1のリリースに伴うものです。Go 1では、言語と標準ライブラリに多くの後方互換性のない変更が導入されました。その中には、binary.TotalSize関数とbufio.NewReaderSize関数の挙動変更または削除が含まれていました。

以前のバージョンでは、これらの関数は特定のシグネチャや挙動を持っていましたが、Go 1ではより洗練されたAPI設計を目指し、変更が加えられました。特に、binary.TotalSizeはbinary.Sizeに置き換えられ、bufio.NewReaderSizeは無効なサイズ引数に対してエラーを返さなくなり、内部で調整されるようになりました。

このような破壊的変更は、既存のGoコードベースに影響を与えるため、開発者がGo 1に移行する際にコードを更新する必要がありました。このコミットの目的は、Go 1のドキュメント（doc/go1.htmlとdoc/go1.tmpl）を更新し、これらの変更がコンパイラによって捕捉されることを明確に伝えることで、開発者の移行作業を支援することにありました。これにより、手動でのコードレビューだけでなく、コンパイラが古いコードの使用を自動的に検出してくれるという重要な情報を提供しています。

前提知識の解説

Go 1リリース

Go 1は、Go言語の最初の安定版リリースであり、言語仕様と標準ライブラリのAPIを安定させることを目的としていました。Go 1以降、Goチームは後方互換性を維持することを強く約束しており、Go 1で導入された変更は、その後のGo言語の進化の基盤となりました。Go 1のリリースは、Go言語が実用的なプログラミング言語として広く採用されるための重要なマイルストーンでした。

binary.TotalSizeとbinary.Size

Go 1以前のGo言語には、binary.TotalSizeという関数が存在しました。この関数は、Goのデータ構造がバイナリ形式でエンコードされた場合の合計サイズを計算するために使用されていました。しかし、Go 1ではこの関数がbinary.Sizeに置き換えられました。

  • binary.TotalSize: Go 1以前に存在した関数で、バイナリエンコードされたデータの合計サイズを計算しました。
  • binary.Size: Go 1でbinary.TotalSizeの代わりに導入された関数です。binary.TotalSizeがreflect.Valueを引数にとっていたのに対し、binary.Sizeはinterface{}を引数にとるようになりました。これにより、より柔軟な型を受け入れられるようになりましたが、既存のコードは手動で更新する必要がありました。

bufio.NewReaderSize

bufio.NewReaderSizeは、指定されたバッファサイズを持つbufio.Readerを作成するための関数です。bufio.Readerは、io.Readerインターフェースをラップし、内部バッファを使用してI/O操作の効率を向上させます。

Go 1以前では、bufio.NewReaderSizeに無効なサイズ引数（例えば、小さすぎる値）が渡された場合、エラーを返す可能性がありました。しかし、Go 1ではこの挙動が変更され、無効なサイズが指定された場合でもエラーを返さず、内部で適切なサイズに調整されるようになりました。これにより、関数の呼び出し側でエラーハンドリングの必要がなくなりましたが、既存のコードでエラーをチェックしていた部分は変更が必要となりました。

go fixツール

go fixは、Go言語のツールチェーンに含まれるコマンドラインツールです。Go言語のバージョンアップに伴うAPIの変更や非推奨化に対応するため、古いGoコードを自動的に新しいAPIに書き換える機能を提供します。これにより、開発者は手動で大量のコードを修正する手間を省くことができます。ただし、すべての変更を自動的に修正できるわけではなく、一部の変更は手動での対応が必要となります。

技術的詳細

このコミットは、Go 1におけるbinary.TotalSizeとbufio.NewReaderSizeの変更が、コンパイラによって検出されるようになったという事実をドキュメントに反映させるものです。

具体的には、以下の点が技術的な詳細として挙げられます。

  1. binary.TotalSizeの変更:

    • Go 1では、binary.TotalSize関数が削除され、代わりにbinary.Size関数が導入されました。
    • binary.TotalSizeはreflect.Valueを引数としていましたが、binary.Sizeはinterface{}を引数として受け取るようになりました。
    • この変更は、既存のコードがbinary.TotalSizeを使用している場合、コンパイルエラーを引き起こします。これは、関数名が変更されただけでなく、引数の型も変更されたためです。
    • ドキュメントの更新は、このコンパイルエラーが意図されたものであり、開発者が手動でbinary.Sizeへの移行を行う必要があることを示唆しています。

  2. bufio.NewReaderSizeの変更:

    • Go 1では、bufio.NewReaderSize関数が無効なサイズ引数を受け取った際にエラーを返さなくなりました。
    • 以前は、無効なサイズが指定された場合、関数はエラーを返す可能性があり、呼び出し側でそのエラーを処理する必要がありました。
    • Go 1以降は、無効なサイズが指定されても、関数は内部でサイズを調整し、常に有効な*bufio.Readerを返します。
    • この変更により、bufio.NewReaderSizeの呼び出しでエラーをチェックしていた既存のコードは、コンパイルエラーになるか、または不要なエラーチェックを行うことになります。
    • ドキュメントの更新は、この変更もコンパイラによって検出されることを強調しており、開発者がエラーチェックのロジックを削除または修正する必要があることを示しています。

  3. コンパイラによる検出の強調:

    • このコミットの最も重要な点は、「コンパイラが古いコードを捕捉する」という点をドキュメントで明確にしていることです。
    • Go 1のような大規模な破壊的変更を含むリリースでは、開発者が自身のコードを新しいAPIに適合させる必要があります。
    • コンパイラがこれらの変更をエラーとして検出してくれることで、開発者は手動でコードベース全体を検索して変更箇所を見つける手間を省くことができます。コンパイルエラーが発生した箇所を修正すればよいという指針を提供しています。
    • これは、go fixツールが自動的に修正できないような、より根本的なAPIの変更に対して特に重要です。

これらの変更は、Go言語のAPI設計の進化と、より堅牢で使いやすい標準ライブラリを目指すGoチームの姿勢を反映しています。

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

このコミットでは、doc/go1.htmlとdoc/go1.tmplという2つのドキュメントファイルが変更されています。これらのファイルは、Go 1のリリースノートや移行ガイドの一部を構成していると考えられます。

変更内容は、主にUpdatingセクションの記述の修正です。

doc/go1.htmlとdoc/go1.tmplの変更点:

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -875,8 +875,7 @@ If the argument size is too small or invalid, it is adjusted.
 
 <p>
 <em>Updating</em>:
-These functions are rarely used, and code must be updated by hand.
-All that is required is to drop the second return value.
+What little code is affected will be caught by the compiler and must be updated by hand.
 </p>
 
 <h3 id=\"crypto_elliptic\">The crypto/elliptic package</h3>
@@ -937,7 +936,7 @@ In Go 1, the <code>binary.TotalSize</code></a> function is no longer exported.\n 
 <p>
 <em>Updating</em>:
-Code that depends on the function will need to be updated.
+What little code is affected will be caught by the compiler and must be updated by hand.
 </p>
 
 <h3 id=\"encoding_xml\">The encoding/xml package</h3>

同様の変更がdoc/go1.tmplにも適用されています。

コアとなるコードの解説

変更されたコードは、Go 1のドキュメントにおける「Updating」（更新）セクションの記述です。このセクションは、Go 1への移行時に開発者が既存のコードをどのように修正すべきかについての手引きを提供しています。

変更前は、bufio.NewReaderSize（または類似の関数）に関する記述で、「これらの関数はめったに使われず、コードは手動で更新する必要がある。必要なのは2番目の戻り値を削除することだけだ」と書かれていました。また、binary.TotalSizeに関する記述では、「この関数に依存するコードは更新する必要がある」と書かれていました。

このコミットによって、これらの記述は以下のように変更されました。

「影響を受けるわずかなコードは、コンパイラによって捕捉され、手動で更新する必要がある。」

この変更の意図は以下の通りです。

  1. コンパイラの役割の強調: 以前の記述では、手動での更新が必要であることだけが強調されていましたが、新しい記述では、コンパイラがこれらの変更をエラーとして検出してくれるという重要な情報が追加されています。これは、開発者がGo 1への移行作業を行う際に、コンパイルエラーを修正することで対応できるという明確な指針を与えます。
  2. 簡潔化と正確性の向上: 以前の記述は、bufio.NewReaderSizeの特定の変更（2番目の戻り値の削除）に焦点を当てていましたが、新しい記述はより一般的で、binary.TotalSizeの変更にも適用できる表現になっています。これにより、ドキュメントの正確性と汎用性が向上しています。
  3. 開発者体験の改善: コンパイラが変更を捕捉するという事実は、開発者にとって大きな助けとなります。手動でコードベースを検索する代わりに、コンパイルエラーが発生した箇所を修正すればよいという安心感を提供します。

このドキュメントの更新は、Go 1の破壊的変更に対するGoチームの配慮を示しており、開発者がスムーズに新しいバージョンへ移行できるよう支援する意図が込められています。

関連リンク

参考にした情報源リンク