phant-app/go-naming

Go Naming Conventions

Normative: Core naming rules (MixedCaps, no underscores) are required per Google's canonical Go style guide. Advisory guidance provides best practices for clarity and maintainability.

Core Principle

Names should:

• Not feel repetitive when used
• Take context into consideration
• Not repeat concepts that are already clear

Naming is more art than science—Go names tend to be shorter than in other languages.

---

MixedCaps (Required)

Normative: All Go identifiers must use MixedCaps.

Go uses MixedCaps or mixedCaps (camel case), never underscores (snake case).

// Good
MaxLength    // exported constant
maxLength    // unexported constant
userID       // variable
URLParser    // type with initialism

// Bad
MAX_LENGTH   // no snake_case
max_length   // no underscores
User_Name    // no underscores in names

Exceptions for Underscores

Names may contain underscores only in these cases:

1. Test functions: TestFoo_InvalidInput, BenchmarkSort_LargeSlice
2. Generated code: Package names only imported by generated code
3. OS/cgo interop: Low-level libraries matching OS identifiers (rare)

Note: Filenames are not Go identifiers and may contain underscores.

---

Package Names

Normative: Packages must be lowercase with no underscores.

Package names must be:

• Concise and lowercase only
• No underscores (e.g., tabwriter not tab_writer)
• Not likely to shadow common variables

// Good: user, oauth2, k8s, tabwriter
// Bad: user_service (underscores), UserService (uppercase), count (shadows var)

Avoid Uninformative Names

Advisory: Don't use generic package names.

Avoid names that tempt users to rename on import: util, common, helper, model, base. Prefer specific names: stringutil, httpauth, configloader.

Import Renaming

When renaming imports, the local name must follow package naming rules: import foopb "path/to/foo_go_proto" (not foo_pb with underscore).

---

Interface Names

Advisory: One-method interfaces use "-er" suffix.

By convention, one-method interfaces are named by the method name plus an -er suffix to construct an agent noun:

// Standard library examples
type Reader interface { Read(p []byte) (n int, err error) }
type Writer interface { Write(p []byte) (n int, err error) }
type Formatter interface { Format(f State, verb rune) }
type CloseNotifier interface { CloseNotify() <-chan bool }

Honor canonical method names (Read, Write, Close, String) and their signatures. If your type implements a method with the same meaning as a well-known type, use the same name—call it String not ToString.

---

Receiver Names

Normative: Receivers must be short abbreviations, used consistently.

Receiver variable names must be:

• Short (one or two letters)
• Abbreviations for the type itself
• Consistent across all methods of that type

| Long Name (Bad) | Better Name | |-----------------------------|--------------------------| | func (tray Tray) | func (t Tray) | | func (info *ResearchInfo) | func (ri *ResearchInfo)| | func (this *ReportWriter) | func (w *ReportWriter) | | func (self *Scanner) | func (s *Scanner) |

// Good - consistent short receiver
func (c *Client) Connect() error
func (c *Client) Send(msg []byte) error
func (c *Client) Close() error

// Bad - inconsistent or long receivers
func (client *Client) Connect() error
func (cl *Client) Send(msg []byte) error
func (this *Client) Close() error

---

Constant Names

Normative: Constants use MixedCaps, never ALL_CAPS or K prefix.

// Good
const MaxPacketSize = 512
const defaultTimeout = 30 * time.Second

// Bad
const MAX_PACKET_SIZE = 512    // no snake_case
const kMaxBufferSize = 1024    // no K prefix

Name by Role, Not Value

Advisory: Constants should explain what the value denotes.

// Good - names explain the role
const MaxRetries = 3
const DefaultPort = 8080

// Bad - names just describe the value
const Three = 3
const Port8080 = 8080

---

Initialisms and Acronyms

Normative: Initialisms maintain consistent case throughout.

Initialisms (URL, ID, HTTP, API) should be all uppercase or all lowercase:

| English | Exported | Unexported | |-----------|-----------|------------| | URL | URL | url | | ID | ID | id | | HTTP/API | HTTP | http | | gRPC/iOS | GRPC/IOS | gRPC/iOS |

// Good: HTTPClient, userID, ParseURL()
// Bad: HttpClient, orderId, ParseUrl()

---

Function and Method Names

Getters and Setters

Advisory: Don't use Get prefix for simple accessors.

If you have a field called owner (unexported), the getter should be Owner() (exported), not GetOwner(). The setter, if needed, is SetOwner():

// Good
owner := obj.Owner()
if owner != user {
    obj.SetOwner(user)
}

// Bad: c.GetName(), u.GetEmail(), p.GetID()

Use Compute or Fetch for expensive operations: db.FetchUser(id), stats.ComputeAverage().

Naming Conventions

Advisory: Use noun-like names for getters, verb-like names for actions.

// Noun-like for returning values
func (c *Config) JobName(key string) string
func (u *User) Permissions() []Permission

// Verb-like for actions
func (c *Config) WriteDetail(w io.Writer) error

Type Suffixes

When functions differ only by type, include type at the end: ParseInt(), ParseInt64(), AppendInt(), AppendInt64().

For a clear "primary" version, omit the type: Marshal() (primary), MarshalText() (variant).

---

Variable Names

Variable naming balances brevity with clarity. Key principles:

• Scope-based length: Short names (i, v) for small scopes; longer, descriptive names for larger scopes
• Single-letter conventions: Use familiar patterns (i for index, r/w for reader/writer)
• Avoid type in name: Use users not userSlice, name not nameString
• Prefix unexported globals: Use _ prefix for package-level unexported vars/consts to prevent shadowing

// Good - scope-appropriate naming
for i, v := range items { ... }           // small scope
pendingOrders := filterPending(orders)    // larger scope

// Good - unexported global with prefix
const _defaultPort = 8080

For detailed guidance: See references/VARIABLES.md

---

Avoiding Repetition

Go names should not feel repetitive when used. Consider the full context:

• Package + symbol: widget.New() not widget.NewWidget()
• Receiver + method: p.Name() not p.ProjectName()
• Context + type: In package sqldb, use Connection not DBConnection

// Bad - repetitive
func (c *Config) WriteConfigTo(w io.Writer) error
package db
func LoadFromDatabase() error  // db.LoadFromDatabase()

// Good - concise
func (c *Config) WriteTo(w io.Writer) error
package db
func Load() error              // db.Load()

For detailed guidance: See references/REPETITION.md

---

Quick Reference

| Element | Rule | Example | |---------|------|---------| | Package | lowercase, no underscores | package httputil | | Exported | MixedCaps, starts uppercase | func ParseURL() | | Unexported | mixedCaps, starts lowercase | func parseURL() | | Receiver | 1-2 letter abbreviation | func (c *Client) | | Constant | MixedCaps, never ALL_CAPS | const MaxSize = 100 | | Initialism | consistent case | userID, XMLAPI | | Variable | length ~ scope size | i (small), userCount (large) |

See Also

• For interface design patterns: go-interfaces
• For core style principles: go-style-core
• For error handling patterns: go-error-handling
• For testing best practices: go-testing
• For defensive programming: go-defensive
• For performance optimization: go-performance