Go言語入門：Goドキュメント -Syntax:Lists-

スポンサーリンク
Go言語入門：Goドキュメント -Syntax:Lists- ノウハウ
Go言語入門：Goドキュメント -Syntax:Lists-
この記事は約12分で読めます。
よっしー
よっしー

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

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

スポンサーリンク

背景

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

Go Doc Comments - The Go Programming Language
go.dev

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

構文 -リスト-

リストは、インデントされた行または空白行の範囲（そうでなければ次のセクションで説明するコードブロックとなるもの）で、最初のインデント行が箇条書きマーカーまたは番号付きリストマーカーで始まるものです。

箇条書きマーカーは、アスタリスク、プラス、ダッシュ、またはUnicodeの黒丸（*, +, -, •; U+002A, U+002B, U+002D, U+2022）の後に空白またはタブが続き、その後にテキストが続きます。箇条書きリストでは、箇条書きマーカーで始まる各行が新しいリスト項目を開始します。

例えば：

package url

// PublicSuffixListはドメインのパブリックサフィックスを提供します。例えば：
//   - "example.com"のパブリックサフィックスは"com"、
//   - "foo1.foo2.foo3.co.uk"のパブリックサフィックスは"co.uk"、そして
//   - "bar.pvt.k12.ma.us"のパブリックサフィックスは"pvt.k12.ma.us"です。
//
// PublicSuffixListの実装は、複数のゴルーチンによる同時使用に対して安全でなければなりません。
//
// 常に""を返す実装は有効であり、テストには有用かもしれませんが、安全ではありません：
// これはfoo.comのHTTPサーバーがbar.comのCookieを設定できることを意味します。
//
// パブリックサフィックスリストの実装はgolang.org/x/net/publicsuffixパッケージにあります。
type PublicSuffixList interface {
    ...
}

番号付きリストマーカーは、任意の長さの10進数の後にピリオドまたは右括弧、次に空白またはタブ、そしてテキストが続くものです。番号付きリストでは、数字リストマーカーで始まる各行が新しいリスト項目を開始します。項目番号はそのままで、再番号付けされることはありません。

例えば：

package path

// Cleanは、純粋に字句処理によって、pathと等価な最短のパス名を返します。
// これは、これ以上処理できなくなるまで、次のルールを繰り返し適用します：
//
//  1. 複数のスラッシュを単一のスラッシュに置き換えます。
//  2. 各 . パス名要素（現在のディレクトリ）を削除します。
//  3. 各内部 .. パス名要素（親ディレクトリ）と、それに先行する非 .. 要素を削除します。
//  4. ルートパスの先頭にある .. 要素を削除します：
//     つまり、パスの先頭の"/.."を"/"に置き換えます。
//
// 返されるパスは、それがルート"/"である場合にのみスラッシュで終わります。
//
// このプロセスの結果が空の文字列である場合、Cleanは文字列"."を返します。
//
// Rob Pikeの"[Lexical File Names in Plan 9]"も参照してください。
//
// [Lexical File Names in Plan 9]: https://9p.io/sys/doc/lexnames.html
func Clean(path string) string {
    ...
}

リスト項目には段落のみが含まれ、コードブロックやネストされたリストは含まれません。これにより、スペースのカウントの微妙さや、不整合なインデントでタブが何スペースとしてカウントされるかという質問を避けることができます。

gofmtは箇条書きリストを、箇条書きマーカーとしてダッシュを使用し、ダッシュの前に2つのスペースのインデント、継続行には4つのスペースのインデントを使用するように再フォーマットします。

gofmtは番号付きリストを、数字の前に1つのスペース、数字の後にピリオド、そして継続行には同様に4つのスペースのインデントを使用するように再フォーマットします。

gofmtはリストと先行する段落の間の空白行を保持しますが、必須ではありません。リストと後続の段落または見出しの間には空白行を挿入します。

解説と使用例

Go言語のドキュメントコメントにおける「リスト」機能は、箇条書きや番号付きリストを作成するための構文を提供します。これにより、情報を整理して読みやすくすることができます。以下に詳細な解説と使用例を示します。

1. 箇条書きリスト（Bullet Lists）

箇条書きリストは、各項目の先頭に特定のマーカー（*, +, -, •）を置くことで作成します。gofmtは自動的にこれらを - マーカーに統一します。

使用例:

package config

// ConfigOptions は設定オプションを表します。
// 以下のオプションがサポートされています：
//
//   - LogLevel: ログレベルを指定します（"debug", "info", "warn", "error"）
//   - MaxRetries: 再試行の最大回数を指定します
//   - Timeout: 操作のタイムアウト時間（秒単位）を指定します
//   - EnableCache: キャッシュを有効にするかどうかを指定します
type ConfigOptions struct {
    LogLevel    string
    MaxRetries  int
    Timeout     int
    EnableCache bool
}

gofmtによって、箇条書きマーカーの前に2スペースのインデント、マーカーの後に1スペース、複数行にわたる項目には4スペースのインデントが適用されます。

2. 番号付きリスト（Numbered Lists）

番号付きリストは、各項目の先頭に数字とピリオドまたは括弧を置くことで作成します。gofmtは自動的にピリオド形式に統一します。

使用例:

package http

// HandleRequest はHTTPリクエストを処理します。
// 処理のステップは以下の通りです：
//
//  1. リクエストヘッダーを検証します
//  2. ユーザー認証を行います
//  3. リクエストボディを解析します
//  4. ビジネスロジックを実行します
//  5. レスポンスを生成して返します
//
// エラーが発生した場合、適切なHTTPステータスコードとエラーメッセージが返されます。
func HandleRequest(req *Request) *Response {
    // 実装
    return nil
}

gofmtによって、数字の前に1スペースのインデント、数字の後にピリオドと1スペース、複数行にわたる項目には4スペースのインデントが適用されます。

3. リストの書式とインデント

リストの書式化には、以下のルールが適用されます：

  1. リスト項目は段落のみを含み、コードブロックやネストされたリストは含まれません
  2. gofmtは箇条書きマーカーをダッシュ（-）に統一します
  3. 箇条書きリストは2スペースのインデントで始まります
  4. 番号付きリストは1スペースのインデントで始まります
  5. 継続行は4スペースのインデントが使用されます

使用例（複数行にわたるリスト項目）:

package validation

// Validate は入力データを検証します。
// 以下の検証ルールが適用されます：
//
//   - 必須フィールド：すべての必須フィールドが存在し、空でないことを
//     確認します。欠落しているフィールドがある場合はエラーが返されます。
//
//   - 型検証：各フィールドが期待される型と一致することを確認します。
//     型が一致しない場合、変換エラーが返されます。
//
//   - 範囲検証：数値フィールドが指定された範囲内にあることを確認します。
//     範囲外の値はエラーになります。
func Validate(data map[string]interface{}) error {
    // 実装
    return nil
}

この例では、各リスト項目が複数行にわたっており、継続行は4スペースのインデントが適用されています。

4. リストと段落の区切り

gofmtは、リストと先行する段落の間の空白行を保持しますが、必須ではありません。一方、リストと後続の段落または見出しの間には自動的に空白行を挿入します。

使用例:

package storage

// FileStorage はファイルベースのストレージ実装です。
// サポートされる操作は以下の通りです：
//
//   - Read: ファイルからデータを読み込みます
//   - Write: ファイルにデータを書き込みます
//   - Delete: ファイルを削除します
//   - List: ディレクトリ内のファイル一覧を取得します
//
// このストレージ実装は、小規模なデータセットやローカルでの開発に適しています。
// 大規模なデータセットや本番環境では、より堅牢なストレージソリューションを検討してください。
type FileStorage struct {
    // フィールド
}

この例では、リストの前後に空白行があり、リストと後続の段落が明確に区別されています。

5. リストのユースケース

Go言語のドキュメントコメントでリストを使用する一般的なケースには以下のようなものがあります：

a. 機能やオプションの列挙

使用例:

package logging

// Logger はアプリケーションのロギング機能を提供します。
// 以下のログレベルがサポートされています：
//
//   - DEBUG: 開発者向けの詳細な情報
//   - INFO: 一般的な情報メッセージ
//   - WARN: 潜在的な問題を示す警告
//   - ERROR: エラー情報
//   - FATAL: アプリケーション終了の原因となる重大なエラー
type Logger struct {
    // フィールド
}
b. 手順やステップの説明

使用例:

package auth

// Authenticate はユーザー認証を行います。
// 認証プロセスは以下の手順で行われます：
//
//  1. ユーザー名とパスワードの入力検証
//  2. パスワードのハッシュ計算
//  3. データベースに保存されているハッシュとの比較
//  4. 認証成功時のセッショントークン生成
//  5. アクセスログへの記録
func Authenticate(username, password string) (string, error) {
    // 実装
    return "", nil
}

c. 制約やルールの説明

使用例:

package validator

// IsValidPassword はパスワードが以下の条件を満たしているかを検証します：
//
//   - 長さが8文字以上であること
//   - 少なくとも1つの大文字を含むこと
//   - 少なくとも1つの小文字を含むこと
//   - 少なくとも1つの数字を含むこと
//   - 少なくとも1つの特殊文字を含むこと
func IsValidPassword(password string) bool {
    // 実装
    return false
}

重要なポイント

  1. リストの種類:
    • 箇条書きリスト: *, +, -, • マーカーを使用（gofmtは - に統一）
    • 番号付きリスト: 数字の後にピリオドまたは括弧を使用（gofmtはピリオドに統一）
  2. インデントルール:
    • 箇条書きリスト: マーカーの前に2スペース、マーカーの後に1スペース
    • 番号付きリスト: 数字の前に1スペース、数字の後にピリオドと1スペース
    • 継続行: 4スペースのインデント
  3. リストの制限:
    • リスト項目は段落のみを含み、コードブロックやネストされたリストは含まれない
    • これにより、インデントの複雑さや解釈の曖昧さを避けることができる
  4. gofmtの自動整形:
    • マーカーの統一（ダッシュまたはピリオド）
    • インデントの調整
    • リストと後続の段落または見出しの間に空白行を挿入
  5. 適切な使用場面:
    • 機能やオプションの列挙
    • 手順やステップの説明
    • 制約やルールの説明
    • 関連する項目のグループ化

Go言語のドキュメントコメントにおけるリスト機能を適切に活用することで、情報を整理し、読みやすく構造化されたドキュメントを作成することができます。特に複雑な手順や複数の選択肢を説明する場合に効果的です。

おわりに 

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

よっしー
よっしー

何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。

それでは、また明日お会いしましょう(^^)

コメント

タイトルとURLをコピーしました