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

よっしー

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

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

背景
Docコメント
変数（var）
1. 解説と使用例
おわりに

背景

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コメントの書き方を説明しています。

変数（var）

変数に関する規約は定数と同じです。例えば、以下はグループ化された変数の例です：

package fs

// 一般的なファイルシステムエラー。
// ファイルシステムによって返されるエラーは、errors.Isを使用して
// これらのエラーと比較できます。
var (
    ErrInvalid    = errInvalid()    // "無効な引数"
    ErrPermission = errPermission() // "権限がありません"
    ErrExist      = errExist()      // "ファイルは既に存在します"
    ErrNotExist   = errNotExist()   // "ファイルが存在しません"
    ErrClosed     = errClosed()     // "ファイルは既に閉じられています"
)

そして、単一の変数の例：

package unicode

// Scripts はUnicodeスクリプトテーブルのセットです。
var Scripts = map[string]*RangeTable{
    "Adlam":                  Adlam,
    "Ahom":                   Ahom,
    "Anatolian_Hieroglyphs":  Anatolian_Hieroglyphs,
    "Arabic":                 Arabic,
    "Armenian":               Armenian,
    ...
}

解説と使用例

Go言語では、変数宣言のドキュメンテーション規約は定数と同様のパターンに従います。以下にそれぞれのパターンの解説と使用例を示します。

1. グループ化された変数

グループ化された変数では、グループ全体を説明するドキュメントコメントと、各変数の簡潔な行末コメントを組み合わせます。

使用例:

package main

import (
    "errors"
    "fmt"
)

// データベース接続に関連するエラー。
// これらのエラーはerrors.Isを使用して比較できます。
var (
    ErrConnectionFailed = errors.New("データベース接続に失敗しました")
    ErrQueryTimeout     = errors.New("クエリがタイムアウトしました")
    ErrInvalidSQL       = errors.New("無効なSQLクエリです")
    ErrNoRows           = errors.New("結果が見つかりません")
)

func simulateDatabaseQuery() error {
    // 例として、接続エラーを返す
    return ErrConnectionFailed
}

func main() {
    err := simulateDatabaseQuery()
    
    if errors.Is(err, ErrConnectionFailed) {
        fmt.Println("データベースに接続できませんでした。ネットワーク設定を確認してください。")
    } else if errors.Is(err, ErrNoRows) {
        fmt.Println("検索条件に一致するデータがありませんでした。")
    } else if err != nil {
        fmt.Printf("予期しないエラーが発生しました: %v\n", err)
    } else {
        fmt.Println("クエリは正常に実行されました")
    }
}

2. 単一の変数

単一の変数では、完全な文で始まるドキュメントコメントを付けます。

使用例:

package main

import (
    "fmt"
)

// DefaultConfig はアプリケーションのデフォルト設定です。
// ユーザーが設定を指定しない場合に使用されます。
var DefaultConfig = struct {
    Host            string
    Port            int
    MaxConnections  int
    Timeout         int
    Debug           bool
}{
    Host:           "localhost",
    Port:           8080,
    MaxConnections: 100,
    Timeout:        30,
    Debug:          false,
}

func main() {
    // デフォルト設定を使用する
    config := DefaultConfig
    
    // 必要に応じて一部の設定を上書きする
    config.Debug = true
    
    fmt.Printf("アプリケーション設定:\n")
    fmt.Printf("  ホスト: %s\n", config.Host)
    fmt.Printf("  ポート: %d\n", config.Port)
    fmt.Printf("  最大接続数: %d\n", config.MaxConnections)
    fmt.Printf("  タイムアウト: %d秒\n", config.Timeout)
    fmt.Printf("  デバッグモード: %v\n", config.Debug)
}

3. パッケージレベルの複雑な変数

複雑なデータ構造やマップのような変数も同様のパターンでドキュメント化します。

使用例:

package main

import (
    "fmt"
)

// HTTPステータスコードとその説明文のマッピング。
// 一般的なHTTPステータスコードを含みます。
var HTTPStatusText = map[int]string{
    200: "OK",
    201: "Created",
    204: "No Content",
    301: "Moved Permanently",
    302: "Found",
    304: "Not Modified",
    400: "Bad Request",
    401: "Unauthorized",
    403: "Forbidden",
    404: "Not Found",
    500: "Internal Server Error",
    503: "Service Unavailable",
}

func GetStatusText(code int) string {
    if text, ok := HTTPStatusText[code]; ok {
        return text
    }
    return "Unknown Status"
}

func main() {
    statusCodes := []int{200, 404, 500, 999}
    
    for _, code := range statusCodes {
        text := GetStatusText(code)
        fmt.Printf("HTTPステータス %d: %s\n", code, text)
    }
}

4. 関数に初期化を委任する変数

変数が複雑な初期化ロジックを持つ場合、init関数や専用の初期化関数を使用することもあります。

使用例:

package main

import (
    "fmt"
    "math/rand"
    "time"
)

// RandomNumbers は、プログラム起動時にランダムに生成された
// 10個の整数のスライスです。
var RandomNumbers []int

// init関数はパッケージがインポートされたときに自動的に実行されます。
func init() {
    // 乱数生成器をシードする
    rand.Seed(time.Now().UnixNano())
    
    // 10個のランダムな数値を生成
    RandomNumbers = make([]int, 10)
    for i := 0; i < 10; i++ {
        RandomNumbers[i] = rand.Intn(100) // 0から99までのランダムな整数
    }
}

func main() {
    fmt.Println("プログラム起動時に生成されたランダムな数値:")
    for i, num := range RandomNumbers {
        fmt.Printf("  数値 %d: %d\n", i+1, num)
    }
    
    // これらの値はプログラムの実行中は変わりません
    fmt.Println("\n同じ値が使用されます:")
    fmt.Printf("  最初の値: %d\n", RandomNumbers[0])
}