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

よっしー

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

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

背景
Docコメント
定数（const）
おわりに

背景

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

定数（const）

Goの宣言構文では、宣言をグループ化することができます。その場合、1つのドキュメントコメントで関連する定数のグループを紹介し、個々の定数は行末の短いコメントだけでドキュメント化することができます。例えば：

package scanner // import "text/scanner"

// Scanの結果は、これらのトークンの1つまたはUnicode文字です。
const (
    EOF = -(iota + 1)
    Ident
    Int
    Float
    Char
    ...
)

時にはグループにドキュメントコメントが全く必要ない場合もあります。例えば：

package unicode // import "unicode"

const (
    MaxRune         = '\U0010FFFF' // 有効なUnicodeコードポイントの最大値。
    ReplacementChar = '\uFFFD'     // 無効なコードポイントを表します。
    MaxASCII        = '\u007F'     // ASCII値の最大値。
    MaxLatin1       = '\u00FF'     // Latin-1値の最大値。
)

一方、グループ化されていない定数は通常、完全な文で始まる完全なドキュメントコメントが必要です。例えば：

package unicode

// Versionはテーブルの派生元となるUnicodeエディションです。
const Version = "13.0.0"

型付き定数は、その型の宣言の隣に表示されるため、型のドキュメントコメントを優先して定数グループのドキュメントコメントを省略することがよくあります。例えば：

package syntax

// Opは単一の正規表現演算子です。
type Op uint8

const (
    OpNoMatch        Op = 1 + iota // 文字列に一致しない
    OpEmptyMatch                   // 空文字列に一致する
    OpLiteral                      // Runesシーケンスに一致する
    OpCharClass                    // 範囲ペアリストとして解釈されるRunesに一致する
    OpAnyCharNotNL                 // 改行以外の任意の文字に一致する
    ...
)

（HTMLでの表示については pkg.go.dev/regexp/syntax#Op を参照してください。）

解説

この文書は、Go言語でのコードドキュメンテーションの書き方のベストプラクティスについて説明しています。特に以下の点が重要です：

グループ化された定数：
- const (...) の形で複数の定数をまとめて宣言できます
- グループ全体に対して1つのドキュメントコメントを書き、個々の定数には短い行末コメントを付けます
iota の使用：
- 例にある iota は、Go言語の特徴的な機能で、連番を自動的に割り当てる際に使用します
- EOF = -(iota + 1) のように使うと、定数に順に値が割り当てられます
型付き定数：
- 型を明示的に指定した定数（例：Op = 1 + iota）では、型自体のドキュメントコメントが重要になります
- この場合、定数グループのコメントよりも型のコメントが優先されることが多いです
ドキュメントコメントのスタイル：
- グループ化された定数：簡潔なグループコメントと行末コメント
- 単独の定数：完全な文で始まる詳細なコメント
- 型付き定数：型のコメントが主、個々の定数は短い説明

Go言語では、このようなドキュメンテーションの規則に従うことで、生成されるドキュメントの可読性と一貫性が向上します。

1. グループ化された定数の例

package main

import (
    "fmt"
)

// HTTPステータスコードを表す定数群
const (
    StatusOK           = 200 // リクエスト成功
    StatusCreated      = 201 // リソース作成成功
    StatusBadRequest   = 400 // 不正なリクエスト
    StatusUnauthorized = 401 // 認証が必要
    StatusForbidden    = 403 // アクセス権限なし
    StatusNotFound     = 404 // リソースが見つからない
)

func main() {
    // 定数の使用例
    statusCode := StatusOK
    
    if statusCode == StatusOK {
        fmt.Println("リクエストは成功しました")
    } else if statusCode == StatusNotFound {
        fmt.Println("リソースが見つかりませんでした")
    }
    
    fmt.Printf("ステータスコード: %d\n", statusCode)
}

2. iotaを使ったグループ化された定数

package main

import (
    "fmt"
)

// 曜日を表す定数
const (
    Sunday = iota    // 0
    Monday           // 1
    Tuesday          // 2
    Wednesday        // 3
    Thursday         // 4
    Friday           // 5
    Saturday         // 6
)

func main() {
    today := Wednesday
    
    fmt.Printf("今日は週の%d日目です\n", today)
    
    if today >= Monday && today <= Friday {
        fmt.Println("平日です")
    } else {
        fmt.Println("週末です")
    }
}

3. 単独の定数の例

package main

import (
    "fmt"
)

// Pi は円周率の近似値です（小数点以下15桁）
const Pi = 3.141592653589793

func main() {
    radius := 5.0
    
    // 円の面積を計算
    area := Pi * radius * radius
    
    fmt.Printf("半径%.1fの円の面積: %.2f\n", radius, area)
}

4. 型付き定数の例

package main

import (
    "fmt"
)

// Direction は移動方向を表す型です
type Direction int

// 方向を表す定数
const (
    North Direction = iota // 北向き
    East                   // 東向き
    South                  // 南向き
    West                   // 西向き
)

// String メソッドを実装することで、Direction型の値を文字列として出力できます
func (d Direction) String() string {
    names := []string{"北", "東", "南", "西"}
    if d < North || d > West {
        return "不明な方向"
    }
    return names[d]
}

func main() {
    var heading Direction = East
    
    fmt.Printf("現在の進行方向: %s\n", heading)
    
    // 右に曲がる（時計回りに90度）
    heading = (heading + 1) % 4
    
    fmt.Printf("右折後の進行方向: %s\n", heading)
}

5. 複雑な例（ビットマスクとしての定数）

package main

import (
    "fmt"
)

// FileMode はファイルのアクセス権限を表します
type FileMode uint32

// ファイルモードの各ビットが表す意味
const (
    ModeDir FileMode = 1 << iota // ディレクトリ
    ModeAppend                   // 追加のみ
    ModeExclusive                // 排他的利用
    ModeTemporary                // 一時ファイル
    ModeSymlink                  // シンボリックリンク
    ModeDevice                   // デバイスファイル
    ModeNamedPipe                // 名前付きパイプ
    ModeSocket                   // Unixドメインソケット
    ModeSetuid                   // setuidビットがセット
    ModeSetgid                   // setgidビットがセット
    ModeCharDevice               // キャラクタデバイス
)

// ファイルモードを文字列で表現するヘルパー関数
func (m FileMode) String() string {
    var result string
    
    if m&ModeDir != 0 {
        result += "[ディレクトリ] "
    }
    if m&ModeSymlink != 0 {
        result += "[シンボリックリンク] "
    }
    if m&ModeTemporary != 0 {
        result += "[一時ファイル] "
    }
    
    if result == "" {
        return "[通常ファイル]"
    }
    return result
}

func main() {
    // ディレクトリかつシンボリックリンク
    var mode FileMode = ModeDir | ModeSymlink
    
    fmt.Printf("ファイルモード: %s\n", mode)
    
    // ディレクトリかどうかを確認
    if mode&ModeDir != 0 {
        fmt.Println("これはディレクトリです")
    }
}