Go 言語コメントの定義と使用 (godoc ツールはコメント内容を抽出します)

プログラム内のコメントの機能は、プログラムに注釈を付けて説明することであり、ソース コードを読むのに便利です。コメント部分はコンパイルシステムがソースコードのコンパイル時に自動的に無視するため、コメントはプログラムの機能実現には影響しません。ソースコードにコメントを適切に追加すると、ソースコードの可読性が向上します。

 

Go 言語のコメントは主に、単一行コメントと複数行コメントの 2 つのカテゴリに分類されます。

• 行コメントと呼ばれる単一行コメントは、コメントの最も一般的な形式であり、 //で始まる単一行コメントはどこでも使用できます。
• 複数行のコメントは、ブロック コメントとして参照され、 /*で始まり*/で終わり、ネストすることはできません。複数行のコメントは、通常、パッケージのドキュメントの説明や、ブロックにコメント化されたコード フラグメントに使用されます。

単一行コメントの形式は次のとおりです。

//单行注释

複数行のコメントの形式は次のとおりです。

/*
第一行注释
第二行注释
…
*/

各パッケージには関連するコメントがあり、package ステートメントを使用してパッケージ名を宣言する前に、対応するコメントを追加して、パッケージの機能と機能を簡単に説明する必要があります。

同時に、パッケージステートメントの前のコメントコンテンツは、デフォルトでパッケージのドキュメントとみなされます。パッケージは複数のファイルに分散させることができますが、コメントする必要があるのはそのうちの 1 つだけです。

次のように、複数のコメントを空白行で区切ることができます。

// パッケージsupermanは、世界を救うためのメソッドを実装します。
//
// 経験から、世界を救う際に役立つ手順はわずかな数しかないことが示されています。
package superman 

コード内の変数、定数、関数、その他のオブジェクトに対応するコメントを追加することをお勧めします。これは、次のコードのenterOrbit 関数のコメントなど、後でコードをメンテナンスするのに役立ちます。

// enterOrbitは、スーパーマンを地球周回軌道に飛行させ、多数の星の救済の可能性を提供します。
func enterOrbit() error {
   ...
} 

開発者がパッケージについて知りたい場合は、godoc を使用してパッケージのドキュメントを表示できます。godoc ツールの使用法を紹介しましょう。

godocツール

godoc ツールは、Go プログラムやパッケージ ファイルからトップレベルの宣言の 1 行目のコメントや各オブジェクトの関連コメントを抽出し、関連ドキュメントを生成します。また、オンラインでドキュメントを閲覧できる Web サーバーとしても使用できます。公式サイト（ https://golang.dev/ ）はこの形で実装されています。

ただし、Go 言語のバージョン 1.13 では godoc ツールが削除されており、 go getコマンドを通じて godoc ツールを取得できます。

go get golang.org/x/tools/cmd/godoc

ファイアウォールの関係で、国内ユーザーはgo getコマンドで godoc ツールを入手できない場合があり、その際は手動で操作する必要があります。

• まず、GitHub ( https://github.com/golang/tools.git ) から golang.org/x/tools パッケージをダウンロードします。
• 次に、ダウンロードしたファイルを GOPATH の下の src\golang.org\x\tools ディレクトリに解凍します。そうでない場合は、手動で作成できます。
• GOPATH の下の src\golang.org\x\tools\cmd\godoc ディレクトリを開き、このディレクトリでコマンド ライン ツールを開き、 go buildコマンドを実行して godoc.exe 実行可能ファイルを生成します。
• 最後に、生成された godoc.exe ファイルを GOPATH 下の bin ディレクトリに移動します。 ( GOPATH 配下の bin ディレクトリを環境変数 Path に追加する必要があります)

上記の操作が完了すると、godoc ツールが使用できるようになりますが、godoc ツールには一般的に次のような用途があります。

• go doc package: パッケージのドキュメント コメントを取得します。たとえば、 go doc fmt godoc によって生成された fmt パッケージのドキュメント コメントを表示します。
• go doc package/subpackage: go doc container/listなど、サブパッケージのドキュメントコメントを取得します。
• go doc package function: パッケージ内の関数のドキュメント コメントを取得します。たとえば、 go doc fmt Printf fmt.Printf() の使用方法を表示します。

次の図は、 go docコマンドを使用してパッケージのドキュメント コメントを取得する方法を示しています。

godoc ツールは、Go インストール ディレクトリの ../go/src にあるコメント コンテンツを取得し、これらのコメント コンテンツを Web サーバーに統合してプレビューすることもできます。コマンド ラインにgodoc -http=:6060入力し、ブラウザを使用して http://localhost:6060 を開くと、ローカル ドキュメント ブラウジング サーバーによって提供されるページが表示されます。