golang-naming

コミュニティでのデフォルト。 samber/cc-skills-golang@golang-naming スキルを明示的に置き換える会社のスキルが優先されます。

Go の命名規則

Go では、短く読みやすい名前が好まれます。大文字・小文字の使い分けによって可視性が決まり、大文字始まりはエクスポートされ、小文字始まりはエクスポートされません。すべての識別子は MixedCaps を使用しなければならず、アンダースコアは決して使用してはいけません。

「明快さは巧妙さに勝ります。」— Go の格言

「アーキテクチャを設計し、コンポーネントに名前を付け、詳細を文書化します。」— Go の格言

ルールを無視するには、コードにコメントを追加してください。

クイックリファレンス

要素	規則	例
パッケージ	小文字、単語は1つ。テストファイルでは _test サフィックスも可	json、http、tabwriter、http_test
ファイル	小文字、アンダースコアも可	user_handler.go
エクスポートされる名前	UpperCamelCase	ReadAll、HTTPClient
エクスポートされない名前	lowerCamelCase	parseToken、userCount
インターフェース	メソッド名 + -er	Reader、Closer、Stringer
構造体	MixedCaps の名詞	Request、FileHeader
定数	MixedCaps（ALL_CAPS ではない）	MaxRetries、defaultTimeout
レシーバー	1〜2文字の略称	func (s *Server)、func (b *Buffer)
エラー変数	Err を接頭辞に付ける	ErrNotFound、ErrTimeout
エラー型	Error を接尾辞に付ける	PathError、SyntaxError
コンストラクター	（単一の型なら）New、（複数の型なら）NewTypeName	ring.New、http.NewRequest
ブール値フィールド	フィールドとメソッドでは is、has、can を接頭辞に付ける	isReady、IsConnected()
テスト関数	Test + 関数名	TestParseToken
頭字語	すべて大文字、またはすべて小文字	URL、HTTPServer、xmlParser
バリエーション：コンテキスト	WithContext を接尾辞に付ける	FetchWithContext、QueryContext
バリエーション：インプレース	In を接尾辞に付ける	SortIn()、ReverseIn()
バリエーション：エラー	Must を接頭辞に付ける	MustParse()、MustLoadConfig()
オプション関数	With + フィールド名	WithPort()、WithLogger()
列挙型（iota）	型名を接頭辞にし、ゼロ値を不明とする	0 の StatusUnknown、StatusReady
名前付き戻り値	説明的な名前にする。ドキュメント化する場合のみ使用	(n int, err error)
エラー文字列	小文字（頭字語を含む）、句読点なし	"image: unknown format"、"invalid id"
インポートエイリアス	衝突する場合のみ、短い名前を使う	mrand "math/rand"、pb "app/proto"
フォーマット関数	f を接尾辞に付ける	Errorf、Wrapf、Logf
テストテーブルのフィールド	got／expected を接頭辞に付ける	input string、expected int

MixedCaps

すべての Go 識別子は MixedCaps（または mixedCaps）を使用しなければなりません。識別子にアンダースコアを使用してはいけません。例外は、テスト関数のサブケース（TestFoo_InvalidInput）、生成コード、OS／cgo との相互運用のみです。これは見た目だけの問題ではなく、Go のエクスポート機構は大文字・小文字の使い分けに依存し、ツールも一貫して MixedCaps を前提としています。

// ✓ Good
MaxPacketSize
userCount
parseHTTPResponse

// ✗ Bad — these conventions conflict with Go's export mechanism and tooling expectations
MAX_PACKET_SIZE   // C/Python style
max_packet_size   // snake_case
kMaxBufferSize    // Hungarian notation

重複した名前を避ける

Go の呼び出し箇所には常にパッケージ名が含まれるため、識別子でそれを繰り返すと読者の時間を無駄にします。たとえば http.HTTPClient では、「HTTP」を2回解析することになります。名前には、パッケージ名、型名、または周囲の文脈ですでに示されている情報を繰り返し含めてはいけません。

// Good — clean at the call site
http.Client       // not http.HTTPClient
json.Decoder      // not json.JSONDecoder
user.New()        // not user.NewUser()
config.Parse()    // not config.ParseConfig()

// In package sqldb:
type Connection struct{}  // not DBConnection — "db" is already in the package name

// Anti-stutter applies to ALL exported types, not just the primary struct:
// In package dbpool:
type Pool struct{}        // not DBPool
type Status struct{}      // not PoolStatus — callers write dbpool.Status
type Option func(*Pool)   // not PoolOption

見落としやすい慣例

これらの慣例は正しいものの、一見してわかりにくく、命名ミスの最も一般的な原因となっています。

コンストラクターの命名： パッケージが主要な型を1つだけエクスポートする場合、コンストラクターには New() を使い、NewTypeName() は使いません。これにより冗長な繰り返しを避けられます。呼び出し側は apiclient.New() と記述し、apiclient.NewClient() とは記述しません。NewTypeName() は、http.NewRequest や http.NewServeMux のように、パッケージに構築可能な型が複数ある場合にのみ使います。

ブール型の構造体フィールド： エクスポートされないブール型フィールドには、必ず is／has／can の接頭辞を付けます。connected や permission のように接頭辞を付けずに記述するのではなく、isConnected、hasPermission とします。エクスポートされるゲッターにも接頭辞を残し、IsConnected() bool とします。こうすると質問として自然に読め、ブール型とほかの型を区別できます。

エラー文字列は略語も含めてすべて小文字にします。 "invalid message ID" ではなく "invalid message id" と記述します。エラー文字列はほかのコンテキストと連結されることが多く（fmt.Errorf("parsing token: %w", err)）、文中に大文字が混在すると不自然に見えるためです。センチネルエラーには、接頭辞としてパッケージ名を含めます。errors.New("apiclient: not found") のように記述します。

列挙型のゼロ値： iota の位置0には、必ず Unknown／Invalid のセンチネルを明示的に配置します。var s Status は暗黙に0になります。これが StatusReady のような実際の状態に対応していると、ステータスが意図的に選択されていないにもかかわらず、選択されたかのようにコードが動作するおそれがあります。

サブテスト名： t.Run() のテーブル駆動テストケース名には、"valid id"、"empty input" のような、説明的な語句をすべて小文字で記述します。"valid ID" や "Valid Input" のような表記は使いません。

詳細なカテゴリ

規則、例、根拠の詳細については、以下を参照してください。

• パッケージ、ファイル、インポートのエイリアス — パッケージ名（単数形の小文字1語）、ファイルの命名規則、インポートのエイリアスパターン（認知負荷を避けるため、名前が衝突する場合にのみ使用）、ディレクトリ構成について説明します。

• 変数、ブール値、レシーバー、略語 — スコープに応じた命名（スコープの長さに合わせる。3行のループでは i、パッケージレベルでは長い名前）、1文字のレシーバーの慣例（Serverには s）、略語の大文字・小文字の使い分け（UrlではなくURL、HttpServerではなくHTTPServer）、ブール値の命名パターン（isReady、hasPrefix）について説明します。

• 関数、メソッド、オプション — ゲッター／セッターのパターン（Goでは Get を省略するため、user.Name() と自然に読めます）、コンストラクターの慣例（New または NewTypeName）、名前付き戻り値（ドキュメント化の目的に限る）、フォーマット関数の接尾辞（Errorf、Wrapf）、関数型オプション（WithPort、WithLogger）について説明します。

• 型、定数、エラー — インターフェースの命名（-er で終わる Reader、Closer）、構造体の命名（名詞、MixedCaps）、定数（ALL_CAPSではなくMixedCaps）、列挙型（StatusReady のように型名を接頭辞にする）、センチネルエラー（ErrNotFound 変数）、エラー型（PathError のように接尾辞を付ける）、エラーメッセージの慣例（小文字、句読点なし）について説明します。

• テストの命名 — テスト関数の命名（TestFunctionName）、テーブル駆動テストのフィールドの慣例（input、expected）、テストヘルパーの命名、サブケースの命名パターンについて説明します。

よくある間違い

間違い	修正方法
ALL_CAPS 定数	Go では強調ではなく公開範囲を大文字・小文字で表すため、MixedCaps（MaxRetries）を使います
GetName() ゲッター	Go では Get を省略します。呼び出し側で user.Name() と読むほうが自然だからです。ただし、真偽値を返す述語には Is／Has／Can の接頭辞を残します。Healthy() bool ではなく IsHealthy() bool とします
Url、Http、Json の頭字語	大文字・小文字が混在する頭字語は曖昧さを生みます（HttpsUrl は Https＋Url でしょうか？）。すべて大文字か、すべて小文字を使います
this や self をレシーバーに使う	Go のメソッドは頻繁に呼び出されるため、視覚的なノイズを減らせるよう、Server なら s のような1～2文字の略称を使います
util、helper パッケージ	これらの名前では内容がわかりません。抽象化の内容を表す具体的な名前を使います
http.HTTPClient のようにパッケージ名を重ねる	呼び出し側には常にパッケージ名が含まれるため、http.Client とすれば「HTTP」を二度読まずに済みます
user.NewUser() コンストラクター	主となる型が1つの場合は New() を使います。user.New() とすれば型名を繰り返さずに済みます
connected bool フィールド	形容詞だけでは曖昧です。isConnected とすれば、フィールド名が真偽値を尋ねる形になります
"invalid message ID" エラー	エラー文字列は頭字語も含めてすべて小文字にする必要があります。"invalid message id" とします
iota の値0に StatusReady を指定する	ゼロ値は番兵値にします。値0に StatusUnknown を指定すると、初期化されていない値を検出できます
"not found" エラー文字列	番兵エラーにはパッケージ名を含めます。"mypackage: not found" とすれば発生元がわかります
型名に実装詳細を含めた userSlice	型名には実装詳細を含めず、何を保持するかを表す users を使います
レシーバー名に一貫性がない	同じ型のメソッド間でレシーバー名を変えると、読み手が混乱します。名前は一貫して同じものを使います
snake_case 識別子	アンダースコアは Go の MixedCaps 規則やツールの想定に反します。mixedCaps を使います
スコープが短いのに長い名前を付ける	名前の長さはスコープに合わせます。3行のループなら i で十分であり、userIndex は冗長です
値に基づいて定数名を付ける	値は変わっても役割は変わりません。ポートが変わっても DefaultPort はそのまま使えますが、Port8080 は使えなくなります
コンテキストを受け取る関数に FetchCtx() を使う	Go では WithContext が標準的な接尾辞です。FetchWithContext() ならすぐに意味がわかります
インプレースで変更する sort() に In がない	読み手は関数が新しい値を返すと考えます。SortIn() とすれば変更を行うことが伝わります
エラー時にパニックする parse()	MustParse() とすれば失敗時にパニックすることを呼び出し側に警告できます。意外な動作は名前で示します
With*、Set*、Use* を混在させる	コードベース全体で一貫性を保ちます。関数オプションには With* を使うのが Go の規約です
複数形のパッケージ名	Go の規約ではパッケージ名は単数形です（net/urls ではなく net/url）。インポートパスの一貫性を保てます
f 接尾辞のない Wrapf	f 接尾辞は書式指定文字列の意味を示します。Wrapf、Errorf とすれば、書式指定引数を渡すよう呼び出し側に伝わります
不要なインポートエイリアス	エイリアスは認知負荷を増やします。名前が衝突する場合にだけエイリアスを付けます。例：mrand "math/rand"
同じ概念に一貫しない名前を使う	同じ概念に user／account／person を使うと、読み手は同義語を把握しなければなりません。名前を1つに統一します

これらの修正を適用するには、既存の識別子の名前を変更する必要があります。安全に変更する方法については samber/cc-skills-golang@golang-gopls スキルを参照してください。このスキルはワークスペース内のすべての呼び出し箇所を更新し、インターフェースの実装を壊す名前変更を拒否します。grep/sed や手動の Edit による名前変更では、この問題を検出できず、気づかないまま見落とします。

リンターで強制する

命名規則に関する多くの問題は、revive、predeclared、misspell、errname などのリンターで自動的に検出できます。設定方法と使い方については samber/cc-skills-golang@golang-lint スキルを参照してください。

相互参照

• → より幅広いフォーマットとスタイルの判断については、samber/cc-skills-golang@golang-code-style スキルを参照してください
• → インターフェースの命名の詳細とレシーバーの設計については、samber/cc-skills-golang@golang-structs-interfaces スキルを参照してください
• → 自動チェック（revive、predeclared、misspell、errname）については、samber/cc-skills-golang@golang-lint スキルを参照してください
• → 命名の修正を適用する際の安全な名前変更については、samber/cc-skills-golang@golang-gopls スキルを参照してください
• → 識別子の新しい名前を決めた後に、大規模な名前変更を安全に適用する方法（gopls Rename/Inline、影響範囲のマッピング、段階的な PR ワークフロー）については、samber/cc-skills-golang@golang-refactoring スキルを参照してください