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:
Test functions: TestFoo_InvalidInput, BenchmarkSort_LargeSlice Generated code: Package names only imported by generated code 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