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

このコミットは、Go言語の公式ドキュメントである「Effective Go」内のタイポ（誤字）を修正するものです。具体的には、パッケージのインポートに関する説明文中の句読点（カンマ）の欠落を補い、文章の意図をより明確にしています。

コミット

commit de4ca13eacecd65d3275ca4aec7a7bb0e8878fe7
Author: Josh Bleecher Snyder <josharian@gmail.com>
Date:   Fri Dec 20 09:59:51 2013 -0800

    doc: fix typo in Effective Go
    
    R=adg, bradfitz
    CC=golang-codereviews
    https://golang.org/cl/44430043

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

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

元コミット内容

--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -350,7 +350,7 @@ not <code>encoding_base64</code> and not <code>encodingBase64</code>.
 </p>
 
 <p>
-The importer of a package will use the name to refer to its contents.
+The importer of a package will use the name to refer to its contents,
 so exported names in the package can use that fact
 to avoid stutter.
 (Don\'t use the <code>import .</code> notation, which can simplify

変更の背景

このコミットは、「Effective Go」ドキュメント内の軽微なタイポを修正することを目的としています。修正された箇所は、Go言語におけるパッケージの命名規則、特に「stuttering（どもり）」と呼ばれる冗長な命名を避けるべきであるという推奨事項を説明している部分です。

元の文章では「The importer of a package will use the name to refer to its contents. so exported names in the package can use that fact to avoid stutter.」となっており、「contents. so」という不自然な区切りになっていました。これは「contents, so」とカンマで接続されるべきであり、前の文が後の文の理由や結果を示す接続詞「so」に続くことを明確にするための修正です。

公式ドキュメントはGo言語のベストプラクティスを伝える重要なリソースであるため、このような小さなタイポであっても、読者の理解を妨げたり、プロフェッショナルな印象を損ねたりする可能性があります。そのため、正確性と可読性を保つために修正されました。

前提知識の解説

Effective Go

「Effective Go」は、Go言語の公式ドキュメントの一つであり、Goプログラマーがより効果的で慣用的な（idiomatic）Goコードを書くためのヒントやベストプラクティスを提供しています。Go言語のツアーや言語仕様書を補完する形で、Goのユニークな特性やイディオムを理解し、活用するための指針を示しています。

このドキュメントは、コードのフォーマット（gofmtの使用）、コメントの書き方、命名規則（パッケージ名、ゲッター、インターフェース、MixedCapsなど）、制御構造（if, for, switch）、関数（多値戻り、名前付き戻り値、defer）、データ構造（newとmake、複合リテラル、配列、スライス、マップ）など、Goプログラミングの多岐にわたる側面をカバーしています。Go言語を学ぶ上で必読の資料とされています。

Go言語の命名規則と「Stuttering（どもり）」

Go言語の命名規則には、「stuttering（どもり）」を避けるという重要な原則があります。これは、変数、フィールド、または関数名において、パッケージ名や型名が冗長に繰り返されることを指します。Go言語では、エクスポートされた識別子（大文字で始まる名前）は常にパッケージ名をプレフィックスとしてアクセスされます（例: package_name.Identifier）。このため、識別子自体にパッケージ名を繰り返すことは冗長であり、可読性を損なうと考えられています。

例:

もしnotificationというパッケージがあった場合、その中の関数をSendNotification()とするのは「stuttering」と見なされます。より慣用的な名前はnotification.Send()です。notification.SendNotification()と書くと、「通知通知を送る」のような冗長な表現になります。
http.HTTPServer{}も「stuttering」の一例で、http.Server{}が推奨されます。

なぜ避けるべきか？

Go言語の設計哲学は、簡潔さと明瞭さを重視しています。パッケージ名がすでにコンテキストを提供しているため、識別子内でその情報を繰り返すことは不要であり、コードを冗長にし、読みにくくします。Goの命名規則は、パッケージ構造を活用して名前を簡潔かつ読みやすく保つことを奨励しています。

例外（stutteringと見なされない場合）:

自身のパッケージ内の型名: fooというパッケージ内にFooという型がある場合、foo.Fooとアクセスされるのは一般的であり、stutteringとは見なされません。これは、fooパッケージがFoo型を定義することに特化しているためです。
明瞭さのため: ごく稀に、曖昧さを避けるために、より冗長な名前が選択されることもありますが、Goの慣例は通常、パッケージのコンテキストを活用した簡潔で明確な名前を推奨します。

このコミットで修正された文章は、まさにこの「stuttering」を避けるべき理由を説明している箇所であり、パッケージをインポートする側がその名前を使って内容を参照するため、パッケージ内のエクスポートされた名前はその事実を利用して「stuttering」を避けることができる、という文脈で述べられています。

技術的詳細

このコミットは、doc/effective_go.htmlファイル内のHTMLコンテンツを修正しています。具体的には、350行目付近の<p>タグで囲まれた段落内のテキストが変更されています。

変更前: The importer of a package will use the name to refer to its contents. so exported names in the package can use that fact

変更後: The importer of a package will use the name to refer to its contents, so exported names in the package can use that fact

この変更は、単にピリオド（.）をカンマ（,）に置き換えるという非常に小さなものですが、文法的な正確性を向上させ、文章の論理的なつながりを明確にしています。

変更前: 「contents. so」という表現は、2つの独立した文が不適切に連結されているように見えます。ピリオドで文が終了しているにもかかわらず、次の文が小文字の「so」で始まっているため、文法的に誤りです。
変更後: 「contents, so」とすることで、「so」が前の節の理由や結果を示す接続詞として機能し、文全体がより自然で流れるような構造になります。これにより、「パッケージをインポートする側がその名前を使って内容を参照するので、パッケージ内のエクスポートされた名前はその事実を利用して…」という因果関係が明確に伝わります。

この修正は、Go言語の公式ドキュメントの品質とプロフェッショナリズムを維持するために重要です。特に「Effective Go」のような、Goプログラミングの規範を示すドキュメントにおいては、文章の正確性もコードの正確性と同様に重視されます。

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

--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -350,7 +350,7 @@ not <code>encoding_base64</code> and not <code>encodingBase64</code>.
 </p>
 
 <p>
-The importer of a package will use the name to refer to its contents.
+The importer of a package will use the name to refer to its contents,
 so exported names in the package can use that fact
 to avoid stutter.
 (Don\'t use the <code>import .</code> notation, which can simplify

具体的には、doc/effective_go.htmlファイルの353行目（変更前）の以下の部分が変更されました。

-The importer of a package will use the name to refer to its contents. +The importer of a package will use the name to refer to its contents,

ピリオド（.）がカンマ（,）に置き換えられています。

コアとなるコードの解説

変更された行は、Go言語のパッケージ命名における「stuttering（どもり）」を避けるべき理由を説明する段落の一部です。

元の文章: The importer of a package will use the name to refer to its contents. so exported names in the package can use that fact to avoid stutter.

この文章は、Go言語のパッケージシステムがどのように機能し、それが命名規則にどう影響するかを説明しています。

The importer of a package will use the name to refer to its contents.
- これは、「パッケージをインポートする側（つまり、そのパッケージを利用するコード）は、そのパッケージの名前を使って、そのパッケージが提供する内容（関数、変数、型など）を参照する」という意味です。例えば、fmtパッケージをインポートした場合、fmt.Printlnのようにfmtという名前を使ってPrintln関数にアクセスします。
so exported names in the package can use that fact to avoid stutter.
- これは、「そのため、パッケージ内でエクスポートされる名前（大文字で始まる名前）は、その事実（インポート側がパッケージ名を使って参照するという事実）を利用して、『stuttering』を避けることができる」という意味です。

変更前は、最初の文がピリオドで終わっており、その後に接続詞である「so」が小文字で続いていました。これは文法的に不自然であり、2つの文が独立しているかのように読めてしまいます。

変更後、ピリオドがカンマに修正されたことで、最初の文と「so」で始まる節が論理的に連結され、より自然な因果関係を示す複合文となりました。これにより、「パッケージをインポートする側がその名前を使って内容を参照するので、パッケージ内のエクスポートされた名前はその事実を利用してstutteringを避けることができる」という、より明確な意味が伝わるようになりました。

この修正は、Go言語の命名規則の背後にある論理を、読者により正確かつスムーズに理解させるための、小さなしかし重要な改善です。

comemo