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

このコミットは、Go言語の公式ドキュメントである doc/code.html、通称「How to write Go code」の記事を簡素化し、新規ユーザーにとってより分かりやすくすることを目的としています。記事の構成と内容が大幅に改訂され、Goコードの書き方やプロジェクトの構成に関する実践的な手順に焦点を当て、詳細な技術的背景の説明は後回しにされています。これにより、Go言語を学び始める人々が、より迅速に開発環境をセットアップし、最初のプログラムを作成できるようになります。

コミット

commit ee923e3f907adbe99352fe27a5a4994f7d9c4917
Author: Andrew Gerrand <adg@golang.org>
Date:   Thu Apr 4 08:19:24 2013 +1100

    doc: simplify How to write Go code article
    
    This version just tells you what to do, rather
    than trying to teach you how it all works.
    Should be much better for newcomers.
    
    R=dave, gary.burd, alcosholik, r
    CC=golang-dev
    https://golang.org/cl/8247044

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

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

元コミット内容

doc: simplify How to write Go code article

このバージョンは、Goがどのように動作するかを教えるのではなく、何をすべきかを伝えるものです。 新規ユーザーにとって、はるかに良いものになるはずです。

変更の背景

この変更の主な背景は、Go言語の学習曲線、特に新規ユーザーにとっての初期の障壁を低減することにありました。以前の「How to write Go code」の記事は、Goの設計思想や内部動作に関する詳細な説明を含んでいましたが、これがかえって初心者を混乱させ、最初のステップを踏み出すのを難しくしているという問題がありました。

コミットメッセージにある「This version just tells you what to do, rather than trying to teach you how it all works. Should be much better for newcomers.」という記述が、この変更の意図を明確に示しています。つまり、ユーザーがGo言語で開発を始めるために必要な最小限かつ最も実践的な情報に焦点を当て、理論的な説明は後回しにすることで、よりスムーズなオンボーディング体験を提供しようとしたのです。

具体的には、GOPATHの設定、ワークスペースの構造、最初のプログラムの作成、ライブラリの利用といった基本的な手順を、より直接的かつ段階的に提示することで、ユーザーが迷うことなくGo開発の第一歩を踏み出せるように改善されました。

前提知識の解説

このコミットの変更内容を理解するためには、以下のGo言語の基本的な概念とツールに関する知識が必要です。

• Goコマンド (go tool): Go言語のビルド、インストール、テスト、フォーマット、依存関係管理など、開発のあらゆる側面を扱うための主要なコマンドラインツールです。例えば、go buildはソースコードをコンパイルし、go installはコンパイルしたバイナリを指定された場所に配置します。
• GOPATH: Go言語のワークスペースのルートディレクトリを指定する環境変数です。Goのツールチェーンは、このGOPATHを基準にしてソースコード、コンパイル済みパッケージ、実行可能バイナリを探します。複数のパスを設定することも可能ですが、通常は単一のパスを設定します。
• Goワークスペース: GOPATHで指定されたディレクトリ構造で、Goのソースコード、コンパイル済みパッケージ、実行可能バイナリが配置されます。標準的には以下の3つのサブディレクトリを持ちます。
  • src: Goのソースファイルがパッケージごとに整理されて格納されます。
  • pkg: コンパイルされたパッケージオブジェクト（.aファイルなど）が格納されます。クロスコンパイルを考慮してOSやアーキテクチャごとのサブディレクトリが作成されます。
  • bin: go installによってビルドされた実行可能コマンド（バイナリ）が格納されます。
• パッケージ (package): Go言語のコードはパッケージにまとめられます。関連する機能を持つコードを論理的にグループ化する単位です。
  • package main: 実行可能なプログラムのエントリポイントとなるパッケージです。main関数を含み、go installによって実行可能バイナリが生成されます。
  • package <name>: ライブラリとして機能するパッケージです。他のパッケージからインポートされて利用されます。パッケージ名は通常、インポートパスの最後の要素と同じになります。
• インポートパス: Goのパッケージを一意に識別するためのパスです。import "fmt"のように標準ライブラリのパッケージをインポートしたり、import "github.com/user/myproject/mypackage"のように外部のパッケージをインポートしたりします。go getコマンドは、このインポートパスに基づいてリモートリポジトリからソースコードを取得します。
• 静的リンク: Goの実行可能バイナリは、通常、必要なすべてのライブラリを内部に含んでおり、外部の共有ライブラリに依存しません。これにより、デプロイが容易になります。

これらの概念は、Go言語で開発を行う上で不可欠であり、このコミットが変更したドキュメントの主要なトピックとなっています。

技術的詳細

このコミットは、doc/code.htmlファイルに対して、主に以下の技術的な変更と構成の再編を行っています。

1. go commandからgo toolへの表記変更:

   • 記事全体で「go command」という表現が「go tool」に統一されています。これは、goが単なるコマンドではなく、Go開発のための包括的なツールセットであることをより正確に反映しています。

2. GOPATHとワークスペースの説明の簡素化と再構成:

   • 以前はGOPATHの設計思想やMakefileとの比較など、より概念的な説明が先行していましたが、変更後は「goツールはコードを特定の形で整理することを要求する」という直接的な説明から始まります。
   • ワークスペースの構造（src, pkg, bin）が明確にリストアップされ、その役割が簡潔に説明されています。
   • GOPATH環境変数の設定方法が、具体的なコマンド例（mkdir $HOME/go, export GOPATH=$HOME/go）とともに、より実践的な手順として提示されています。
   • PATH環境変数への$GOPATH/binの追加も、利便性のために推奨される手順として明確に示されています。

3. インポートパスの推奨規約の変更と具体例の提示:

   • 以前は「example.com/foo/bar」や「code.google.com/p/example/foo/bar」のような一般的なURLベースのインポートパスが推奨されていましたが、変更後はGitHubアカウントを例に「github.com/user」をベースパスとして使用することが強く推奨されています。これは、当時のGoコミュニティにおけるGitHubの普及を反映したものです。
   • 「mkdir -p $GOPATH/src/github.com/user」のように、具体的なディレクトリ作成コマンドが示され、ユーザーが推奨される構造を簡単に構築できるように配慮されています。

4. 「最初のプログラム」と「最初のライブラリ」の導入順序と詳細化:

   • 記事のフローが、まず実行可能なコマンド（package main）を作成する「Your first program」から始まり、次にライブラリ（package newmath）を作成する「Your first library」へと続くように再構成されています。これにより、ユーザーはGoで何ができるかをすぐに体験できます。
   • 各セクションで、ディレクトリの作成、ソースコードの記述、go installやgo buildによるコンパイル・インストール、そして実行までの手順が、コマンドラインの出力例とともに詳細に示されています。
   • 特に「Your first program」では、git init, git add, git commitといったGitの基本的な操作が導入され、ソースコード管理の重要性が示唆されています（ただし、必須ではないことも明記）。

5. パッケージ名の説明の移動と明確化:

   • 以前は「Import paths」の直後に「Package names」の説明がありましたが、変更後は「Your first library」の後に「Package names」セクションが移動しています。これにより、実際にプログラムやライブラリを作成した後に、パッケージ名の規則を学ぶという、より自然な学習フローが実現されています。
   • package mainが実行可能コマンドに必須であること、パッケージ名がインポートパスの最後の要素と一致するというGoの慣習が明確に説明されています。

6. テストの実行例の更新:

   • go testコマンドの実行例も、新しいインポートパスの規約（github.com/user/newmath）に合わせて更新されています。

7. ワークスペースディレクトリツリーの具体例の更新:

   • 記事の最後に示されるワークスペースのディレクトリツリーの例が、変更されたインポートパス（github.com/user/）と、pkgディレクトリ内のOS/アーキテクチャ固有のパス（linux_amd64など）を反映するように更新されています。
   • go installがパッケージオブジェクトをpkgディレクトリに配置する理由（再コンパイルの回避）と、Goの実行可能ファイルが静的にリンクされることの利点が追記されています。

これらの変更は、Go言語の学習ドキュメントを、より実践的で、段階的なチュートリアルへと進化させるための重要なステップでした。

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

このコミットは、doc/code.htmlという単一のHTMLドキュメントファイルを変更しています。変更の性質上、Go言語のソースコードそのものではなく、Go言語に関するドキュメントのコンテンツが変更されています。

変更の概要は以下の通りです。

• ファイル: doc/code.html
• 変更行数: 461行の変更（275行追加、186行削除）

具体的な変更箇所は、HTMLのコンテンツ（主に<p>, <pre>, <ul>, <h3>タグ内のテキスト）の追加、削除、修正です。

主要な変更点の抜粋（diffから読み取れる範囲で）:

• ヘッダーの変更:

  --- a/doc/code.html
  +++ b/doc/code.html
  @@ -6,344 +6,381 @@
   
   <p>
   This document demonstrates the development of a simple Go package and
  -introduces the <a href="/cmd/go/">go command</a>, the standard way to fetch,
  +introduces the <a href="/cmd/go/">go tool</a>, the standard way to fetch,
   build, and install Go packages and commands.
   </p>
  

  go commandからgo toolへの表記変更。

• GOPATHとワークスペースの説明の再構成:

  -<h3><code>GOPATH</code> and workspaces</h3>
  +<h3 id="Workspaces">Workspaces</h3>
  

  セクションのタイトル変更と、GOPATHの説明をワークスペースの説明から分離。

• ワークスペース構造の明確化:

  -<ul>
  -<li><code>src</code> contains Go source files,
  -<li><code>pkg</code> contains compiled package objects, and
  -<li><code>bin</code> contains executable commands.
  -</ul>
  +<ul>
  +<li><code>src</code> contains Go source files organized into packages (one package per directory),
  +<li><code>pkg</code> contains package objects, and
  +<li><code>bin</code> contains executable commands.
  +</ul>
  

  ワークスペースの各ディレクトリの役割がより詳細に説明されています。

• GOPATH設定の具体例の変更:

  -<pre>
  -GOPATH=/home/user/ext:/home/user/mygo
  -</pre>
  +<pre>
  +$ <b>mkdir $HOME/go</b>
  +$ <b>export GOPATH=$HOME/go</b>
  </pre>
  

  具体的なコマンドラインでの設定例が示され、推奨されるGOPATHのパスが$HOME/mygoから$HOME/goに変更されています。

• インポートパスの推奨規約の変更:

  -We'll use <code>example/</code> as our base import path:
  +We'll use <code>github.com/user</code> as our base path. Create a directory
  +inside your workspace in which to keep source code:
  </p>
  
  <pre>
  -$ mkdir -p $GOPATH/src/example
  +$ <b>mkdir -p $GOPATH/src/github.com/user</b>
  </pre>
  

  example/からgithub.com/userへの変更。

• 「最初のプログラム」と「最初のライブラリ」の導入: 以前はnewmathパッケージの作成から始まっていましたが、変更後はhelloコマンドの作成から始まり、その後にnewmathライブラリの作成が続きます。これに伴い、関連するコードブロックや説明が大幅に追加・再配置されています。

• Git操作の追加:

  +<pre>
  +$ <b>cd $GOPATH/src/github.com/user/hello</b>
  +$ <b>git init</b>
  +Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
  +$ <b>git add hello.go</b>
  +$ <b>git commit -m "initial commit"</b>
  +[master (root-commit) 0b4507d] initial commit
  + 1 file changed, 1 insertion(+)
  +  create mode 100644 hello.go
  +</pre>
  

  Gitの初期化とコミットの例が追加されています。

• パッケージ名の説明の移動: Package namesセクションが記事の後半に移動し、より実践的な内容の後に配置されています。

これらの変更は、ドキュメントの構造と内容を、より実践的で段階的な学習体験を提供するように再構築したものです。

コアとなるコードの解説

このコミットにおける「コアとなるコード」とは、Go言語のソースコードそのものではなく、Go言語の学習ドキュメントであるdoc/code.htmlのコンテンツを指します。このドキュメントは、Go言語のプロジェクト構造、GOPATHの設定、パッケージの作成、コマンドのビルドと実行、テストの書き方など、Go開発の基本的なワークフローを説明する上で非常に重要な役割を果たしています。

変更の核心は、「Goがどのように動作するか」という理論的な説明から、「Goで何をすべきか」という実践的な手順へのシフトです。

具体的には、以下の点が重要です。

1. 実践的な手順の優先:

   • 以前のバージョンでは、GOPATHの概念やGoのビルドシステムの設計思想に関する説明が先行していました。しかし、新規ユーザーにとっては、まず「何をすればGoコードを動かせるのか」が最も重要です。
   • この変更では、GOPATHの設定、ワークスペースの作成、最初の「Hello, world」プログラムの記述と実行、そして簡単なライブラリの作成と利用という一連のステップが、より明確なコマンドラインの例とともに提示されています。これにより、ユーザーはすぐに手を動かして結果を確認できるようになります。

2. 具体的なパスと例の更新:

   • GOPATHの推奨パスが$HOME/mygoから$HOME/goに変更されたり、インポートパスの例がexample/からgithub.com/user/に変更されたりしています。これは、当時のGoコミュニティにおける一般的な慣習や、GitHubのようなバージョン管理システムの利用を促進する意図があったと考えられます。より現実的で、ユーザーがそのまま使える例を提供することで、混乱を減らしています。

3. 学習フローの最適化:

   • 「パッケージ名」のような概念的な説明が、実際にプログラムやライブラリを作成するセクションの後に移動されています。これは、まず実践を通じて基本的な操作を習得し、その後に詳細な規則や概念を学ぶという、より効果的な学習アプローチを反映しています。
   • Gitの基本的な操作（git init, git add, git commit）が導入されたことも、現代のソフトウェア開発におけるバージョン管理の重要性を早期に伝える意図があります。

4. 簡潔さと明瞭さの追求:

   • 冗長な説明や、初心者がすぐに理解する必要のない技術的詳細が削除または簡素化されています。例えば、go installがパッケージオブジェクトをpkgディレクトリに配置する理由や、Goのバイナリが静的にリンクされることの利点など、重要な情報は残しつつも、その提示方法がより直接的になっています。

このコミットは、Go言語の普及と新規ユーザーの獲得において、ドキュメントの質がどれほど重要であるかを示しています。技術的な正確さを保ちつつも、ユーザー体験を最優先し、学習の障壁を低減するための優れた改訂例と言えるでしょう。

関連リンク

• Go言語公式サイト: https://go.dev/
• Goコマンドドキュメント: https://go.dev/cmd/go/
• Effective Go: https://go.dev/doc/effective_go.html (Goの命名規則など、より良いGoコードを書くためのガイドライン)
• Go Modules Reference: https://go.dev/ref/mod (現代のGoにおける依存関係管理の標準的な方法。このコミット当時はGOPATHが主流でしたが、現在はGo Modulesが推奨されます。)

参考にした情報源リンク

• GitHubコミットページ: https://github.com/golang/go/commit/ee923e3f907adbe99352fe27a5a4994f7d9c4917
• Go言語公式ドキュメント doc/code.html の変更履歴: このコミットの変更内容を直接確認するために参照しました。
• Go言語の基本的な概念に関する一般的な知識: GOPATH, ワークスペース, goコマンドの動作など。