18. コメントとドキュメンテーション — godoc の慣習

Go のコメントは // で行末まで、または /* ... */ で複数行を書けます。書き方自体は一般的ですが、Go にはコメントをそのままドキュメントとして活用する強い慣習があります。公開する関数や型のすぐ上に書いたコメントは、ドキュメント生成ツールに拾われ、そのままその要素の説明として表示されます。

慣習として、ドキュメントコメントは説明する対象の名前から書き始めます。たとえば関数 Add のコメントは「Add は 2 つの整数を足して返す」のように、Add という名前で始めるのが推奨されるスタイルです。こうしておくと、生成されたドキュメントが「名前 + 説明」の自然な文として読めます。

生成されたドキュメントは go doc コマンドや pkg.go.dev で閲覧できます。コードとドキュメントが同じ場所にあるため、実装を更新したときに説明も合わせて直しやすく、ドキュメントが古くなりにくいのが利点です。下のコードは、公開関数にドキュメントコメントを付けた例です。