Go言語入門：Goドキュメント -Commands-

よっしー

こんにちは。よっしーです(^^)

本日は、Go言語を効果的に使うためのガイドラインについて解説しています。

背景
Docコメント
コマンド
おわりに

背景

Go言語を学び始めて、より良いコードを書きたいと思い、Go言語の公式ドキュメント「Effective Go」を知りました。これは、いわば「Goらしいコードの書き方指南書」になります。単に動くコードではなく、効率的で保守性の高いコードを書くためのベストプラクティスが詰まっているので、これを読んだ時の内容を備忘として残しました。

Go Doc Comments - The Go Programming Language

Docコメント

「Docコメント」は、トップレベルのpackage、const、func、type、var宣言の直前に、改行を挟まずに現れるコメントです。エクスポートされた（大文字で始まる）すべての名前には、docコメントが必要です。

go/docとgo/doc/commentパッケージは、Goソースコードからドキュメントを抽出する機能を提供し、様々なツールがこの機能を利用しています。go docコマンドは、指定されたパッケージやシンボルのdocコメントを検索して表示します。（シンボルとは、トップレベルのconst、func、type、varのことです。）ウェブサーバー pkg.go.dev は、公開Goパッケージのドキュメントを表示します（ライセンスが許可する場合）。そのサイトを提供しているプログラムは golang.org/x/pkgsite/cmd/pkgsite で、プライベートモジュールのドキュメントを表示したり、インターネット接続なしで使用したりするために、ローカルで実行することもできます。言語サーバー gopls は、IDEでGoソースファイルを編集する際にドキュメントを提供します。

このページの残りの部分では、Go docコメントの書き方を説明しています。

コマンド

コマンドのパッケージコメントも似ていますが、パッケージ内のGoシンボルではなく、プログラムの動作を説明します。最初の文は慣例的にプログラム自体の名前で始まり、文の先頭にあるため大文字になります。例えば、gofmtのパッケージコメントの短縮版は以下の通りです：

/*
Gofmt formats Go programs.
It uses tabs for indentation and blanks for alignment.
Alignment assumes that an editor is using a fixed-width font.

Without an explicit path, it processes the standard input. Given a file,
it operates on that file; given a directory, it operates on all .go files in
that directory, recursively. (Files starting with a period are ignored.)
By default, gofmt prints the reformatted sources to standard output.

Usage:

    gofmt [flags] [path ...]

The flags are:

    -d
        Do not print reformatted sources to standard output.
        If a file's formatting is different than gofmt's, print diffs
        to standard output.
    -w
        Do not print reformatted sources to standard output.
        If a file's formatting is different from gofmt's, overwrite it
        with gofmt's version. If an error occurred during overwriting,
        the original file is restored from an automatic backup.

When gofmt reads from standard input, it accepts either a full Go program
or a program fragment. A program fragment must be a syntactically
valid declaration list, statement list, or expression. When formatting
such a fragment, gofmt preserves leading indentation as well as leading
and trailing spaces, so that individual sections of a Go program can be
formatted by piping them through gofmt.
*/
package main

コメントの冒頭は意味的な改行（semantic linefeeds）を使用して書かれており、各新しい文や長いフレーズがそれぞれ別の行になっています。これにより、コードとコメントが進化する際にdiffが読みやすくなります。後半の段落は、たまたまこの慣習に従っておらず、手動で折り返されています。あなたのコードベースに最適な方法で構いません。どちらの方法でも、go docとpkgsiteはdocコメントのテキストを表示する際に再折り返しします。例えば：

$ go doc gofmt
Gofmt formats Go programs. It uses tabs for indentation and blanks for
alignment. Alignment assumes that an editor is using a fixed-width font.

Without an explicit path, it processes the standard input. Given a file, it
operates on that file; given a directory, it operates on all .go files in that
directory, recursively. (Files starting with a period are ignored.) By default,
gofmt prints the reformatted sources to standard output.

Usage:

    gofmt [flags] [path ...]

The flags are:

    -d
        Do not print reformatted sources to standard output.
        If a file's formatting is different than gofmt's, print diffs
        to standard output.
...

インデントされた行は整形済みテキストとして扱われます：それらは再折り返しされず、HTMLやMarkdownの表示でコードフォントで印刷されます。（詳細は以下のSyntaxセクションを参照してください。）

重要ポイント

コマンドドキュメントの特徴
- プログラム名から開始（大文字）
- 動作の説明が中心
- 使用方法とフラグの説明を含む
フォーマットのポイント
- semantic linefeeds（意味的改行）の推奨
- インデントされた部分は整形済みテキスト
- 自動的な再折り返し
構成要素
- 概要説明
- 使用方法（Usage）
- フラグ/オプションの説明
- 詳細な動作説明

良いコマンドドキュメントの例

/*
MyTool analyzes Go source code for potential issues.
It performs static analysis on packages and reports violations.
The tool supports multiple output formats including JSON and plain text.

By default, mytool analyzes the current directory.
Different paths can be specified as arguments.

Usage:

    mytool [flags] [packages]

The flags are:

    -json
        Output results in JSON format.
    -verbose
        Include detailed analysis information.
    -fix
        Automatically fix simple issues where possible.

Examples:

    mytool                     # Analyze current directory
    mytool ./...              # Analyze all subdirectories
    mytool -json pkg/...      # JSON output for pkg tree

Exit codes:

    0     No issues found
    1     Issues found
    2     Error during analysis
*/
package main