Go Guidelines

Overview

Idiomatic Go guidelines based on Effective Go and Google Go Style Guide. Go has its own conventions — writing good Go means embracing them, not porting patterns from other languages.

Core Proverbs

• Clear is better than clever — optimize for readability, not cleverness

• A little copying is better than a little dependency — duplicate small functions rather than import heavy packages

• The zero value should be useful — design types so var x T works without initialization

• Don't communicate by sharing memory; share memory by communicating — use channels

• Errors are values — program with them, don't just check them

• Don't just check errors, handle them gracefully — add context, decide action

• Reflection is never clear — avoid reflect unless building frameworks

Formatting

Rule Detail

Use gofmt

No exceptions — all Go code is gofmt'd

Indentation Tabs, not spaces

Line length No hard limit; break long lines naturally

Braces Opening brace on same line (mandatory — semicolon insertion)

Import Grouping

import ( // 1. Standard library "context" "fmt" "net/http"

// 2. Third-party packages
"github.com/gorilla/mux"
"go.uber.org/zap"

// 3. Internal packages
"myproject/internal/auth"
"myproject/user"

)

Naming Conventions

What Convention Example

Packages Lowercase, single-word, no underscores bufio , strconv

Exported names MixedCaps (upper first letter) ReadWriter

Unexported mixedCaps (lower first letter) readBuf

Getters Owner() not GetOwner()

func (o *Obj) Name() string

Setters SetOwner()

func (o *Obj) SetName(n string)

One-method interfaces Method name + -er suffix Reader , Writer , Stringer

Acronyms All caps throughout URL , HTTP , ID (not Url , Http , Id )

Constants MixedCaps (not ALL_CAPS ) MaxRetries , not MAX_RETRIES

Receivers 1-2 letters, consistent func (s *Server) , not func (server *Server)

Local variables Length proportional to scope size 1-7 lines: i , buf ; larger scopes: descriptive

Doc Comments

// Package sort provides primitives for sorting slices. package sort

// Fprint formats using the default formats and writes to w. // It returns the number of bytes written and any write error. func Fprint(w io.Writer, a ...any) (n int, err error) {

Doc comment rule Detail

Start with the name of the thing // Fprint formats... not // This function formats...

Full sentences Capitalized, ending with period

Package comment in any file One // Package name ... per package

Naming Pitfalls

// BAD: Java/C# naming func GetUserName() string { ... } type IReader interface { ... }

// GOOD: Go naming func UserName() string { ... } type Reader interface { ... }

// BAD: stuttering in constructors widget.NewWidget() user.NewUser()

// GOOD: package name provides context widget.New() user.New()

// BAD: ALL_CAPS constants const MAX_RETRIES = 3

// GOOD: MixedCaps — name by role, not value const MaxRetries = 3

Control Structures

Rule Detail

Use if init statements if err := f(); err != nil { } — keeps scope tight

Early return Avoid else after return

for has three forms C-style, while, infinite

range is idiomatic Prefer for k, v := range over index-based loops

Range on string Iterates runes (UTF-8), not bytes

Switch has no fall-through Unlike C; use comma-separated cases for multiple matches

Switch on true Replaces if-else chains cleanly

Type switch switch v := value.(type) for interface type dispatch

Full code examples: resources/types-functions.md

Functions

Rule Detail

Return (value, error)

The Go pattern for fallible operations

Named return values Document meaning in godoc; naked returns OK in short functions only

defer runs on any return path Including panics; arguments evaluated immediately

defer is LIFO Last deferred runs first

Use defer for cleanup Files, locks, connections

Full code examples: resources/types-functions.md

Data Types

new vs make

Function Returns Use for Initializes

new(T)

*T

Any type Zeroed memory

make(T, ...)

T

Slices, maps, channels only Internal data structures

Slices

Slice rule Detail

Always use return value of append

Underlying array may move

Pre-allocate with make([]T, 0, cap)

When size is known or estimable

len(s) vs cap(s)

Length is current size, capacity is maximum before reallocation

Nil slice is valid len(nil) == 0 , append(nil, x) works

Prefer nil for empty slices var s []T not s := []T{} — nil encodes to null in JSON, empty literal to []

Maps

Map rule Detail

Zero value for missing key m["absent"] returns zero, not error

Always use comma-ok for presence check v, ok := m[key]

Not safe for concurrent access Use sync.Map or mutex

Iteration order is random Don't rely on order

Full code examples: resources/types-functions.md

Design Principles

Zero Values Should Be Useful

Design types so var x T works without initialization. Example: var buf bytes.Buffer is ready to use with no New() call. Nil fields should fall back to sensible defaults.

Don't Copy Types with Locks

Copying a sync.Mutex copies its state — undefined behavior. Always use pointer receivers on types containing locks.

A Little Copying > A Little Dependency

Duplicate small utility functions rather than importing a heavy package for one helper.

Security

Rule Detail

crypto/rand not math/rand

For keys, tokens, secrets — math/rand is predictable

Build tags for syscall

//go:build linux when using platform-specific syscalls

Build tags for cgo

//go:build cgo — cgo sacrifices memory safety and cross-compilation

Avoid unsafe package Voids all type safety and compatibility guarantees

Avoid reflect

Obscures intent, removes compile-time safety

Methods

Pointer vs Value Receivers

Receiver Can modify? Called on Use when

func (t T) Method()

No (copy) Values and pointers Read-only, small types

func (t *T) Method()

Yes Pointers only* Mutation, large structs

• Go auto-takes address for addressable values.

• Don't pass pointers to small basic types — pass values

• Consistency: if any method needs pointer receiver, all should use pointer

Full code examples: resources/patterns.md

Interfaces

Design Principles

Interface rule Detail

Keep interfaces small 1-2 methods ideal

Accept interfaces, return concrete types Maximum flexibility for callers

Don't export implementation types when interface suffices Return interface from constructors

Interfaces are satisfied implicitly No implements keyword

Name one-method interfaces with -er

Reader , Writer , Closer , Stringer

Define in consuming package Not in implementing package

Don't define before use Wait until you have realistic usage

Don't export unused interfaces If only used internally, keep unexported

Prefer synchronous functions Let callers add concurrency — easier to test and reason about

Type Assertions

// Safe form — comma-ok str, ok := value.(string) if !ok { // value is not a string }

// Type switch — multiple type checks switch v := value.(type) { case string: return v case fmt.Stringer: return v.String() default: return fmt.Sprintf("%v", value) }

Embedding

// Interface embedding — compose interfaces type ReadWriter interface { Reader Writer }

// Struct embedding — promote methods type Job struct { Command string *log.Logger // promoted: job.Println() works }

Initialization

Init rule Detail

init() called after all variable declarations Automatic

All imports initialized first Dependency order

Multiple init() per file allowed Run in order

Use for verification Not complex logic

Full code examples: resources/patterns.md

Functional Options Pattern

Use for 3+ optional configuration fields, library APIs, or when defaults should work out of the box. Define type Option func(*T) , create WithX constructors, and apply in NewT(opts ...Option) .

When to use When NOT to use

3+ optional configuration fields 1-2 required parameters — just use arguments

Library APIs (callers shouldn't know internals) Internal structs with few fields — use literal

Defaults should work out of the box Config loaded from file — use a config struct

Full code examples: resources/patterns.md

Constructor & Validation

Pattern When

NewX() *X

Simple construction, always succeeds

NewX() (*X, error)

Validation needed, may fail

MustX() *X

Panics on error — only for compile-time constants or tests

Full code examples: resources/patterns.md

Generics (Go 1.18+)

Use generics for Don't use generics for

Type-safe collections/containers Simple functions that work with interface{}

Algorithm reuse across types When only one type is ever used

Reducing code duplication When it makes code harder to read

Options/builder patterns Premature abstraction

Full code examples: resources/patterns.md

Package Organization

// Domain-based (preferred for applications) myapp/ ├── user/ # User domain │ ├── user.go │ ├── store.go │ └── handler.go ├── order/ # Order domain │ ├── order.go │ └── service.go ├── internal/ # Private packages │ └── db/ └── cmd/ └── server/main.go

// Flat (for libraries and small services) mylib/ ├── mylib.go # Primary types and functions ├── option.go # Options pattern ├── mylib_test.go └── internal/ # Implementation details

Rule Detail

cmd/

Entry points — main packages

internal/

Private — compiler-enforced, cannot be imported outside module

pkg/

Optional — public library code (some projects skip this)

Avoid models/ , utils/ , helpers/

Too generic — organize by domain

One package = one purpose If you can't name it in one word, split it

Testing

Testing rule Detail

_test.go suffix Test files, excluded from production builds

Test prefix Functions must start with TestXxx(t *testing.T)

t.Run for subtests Enables selective running: go test -run TestAdd/positive

t.Helper()

Marks helper functions for better error locations

t.Cleanup()

Deferred cleanup that runs after test completes

t.Parallel()

Opt-in parallel execution within a test

testdata/ directory Test fixtures, ignored by Go tooling

Got before want t.Errorf("Func(%v) = %v, want %v", input, got, want)

t.Error over t.Fatal

Keep going — report all failures in one run

t.Fatal only for setup When test literally cannot proceed

No t.Fatal from goroutines Only call from test function's goroutine

Full code examples: resources/testing-verification.md

Static Verification

Tool Purpose

go vet ./...

Built-in static analysis

golangci-lint run ./...

Comprehensive linter aggregator

go test -race ./...

Detect data races at runtime

go test -count=1 ./...

Disable test caching

go test -cover ./...

Coverage report

Full config and examples: resources/testing-verification.md

Anti-Pattern Quick Reference

Anti-Pattern Better Alternative

GetName() getter Name()

Stuttering: user.UserName

user.Name

interface{} everywhere Specific types or generics

Large interfaces (10+ methods) Small, composed interfaces

Returning error and ignoring it Always handle or explicitly _ =

else after return

Early return pattern

Naked goroutines (fire-and-forget) Track with sync.WaitGroup or errgroup

init() with complex logic Explicit initialization in main()

Mutable package-level vars Pass config explicitly

Value receiver on large struct Pointer receiver

Checking == nil on interface Check concrete value (interfaces have type+value)

panic for expected errors Return error

Underscore imports without comment Document why: import _ "pkg" // register driver

new(T) when make is needed make for slices/maps/channels

Ignoring append return value Always s = append(s, ...)

Config struct with 10+ fields Functional options pattern

No validation in constructor NewX() (*X, error) with validate()

utils/ or helpers/ package Organize by domain, not by kind

models/ package for all types Put types where they're used

Not using t.Helper()

Test helpers report wrong line numbers

Not using t.Cleanup()

Cleanup may not run on t.Fatal()

go test without -race

Data races go undetected

Copying struct with sync.Mutex

Use pointer receiver, never copy

math/rand for secrets crypto/rand for tokens, keys, secrets

In-band errors (-1 , empty string) Return (value, error) or (value, bool)

Defining interface in implementing package Define where consumed

ALL_CAPS constants MixedCaps — Go convention

import . "pkg" (dot import) Makes code origin unclear

Context in struct field Always pass context.Context as first parameter

Clever one-liners Clear, readable multi-line code

reflect for simple tasks Generics or type assertions

Build & Deploy

Always Use Makefile

Before running go build or any build command, check if a Makefile exists. If it does, use it — the Makefile encodes project-specific build steps (ldflags, embedding, code generation) that raw commands miss.

Situation Action

Makefile exists with relevant target make deploy , make build , make test , etc.

Makefile exists, no matching target List targets, pick closest match

No Makefile Fall back to go build , go test , etc.

Permissions & Ownership

Before building or deploying, check file permissions and ownership. Fix to match the project majority:

Identify majority owner:group

stat -c '%U:%G' * | sort | uniq -c | sort -rn | head -5

Fix if needed

chown -R <user>:<group> .

Temporary Files

File type Location

Build intermediates, scratch files /tmp — never the project directory

Final build artifacts Project output dir or $GOBIN

Downloaded dependencies Standard location (~/go/pkg/ )

Exception: If project instructions (CLAUDE.md, Makefile) specify a different temp location, follow those.

Test File Placement

Test type Location

Temporary (debugging, one-off) /tmp

Permanent, Go convention *_test.go beside the source file

Permanent, integration/e2e tests/ directory (create if it doesn't exist)

Specific instructions exist Follow those

Resources

Detailed code examples are organized into resource files for progressive disclosure:

• Types, Functions & Control Flow — Control structure patterns (if /for /switch ), function signatures, defer, new vs make , composite literals, slices, maps, and printing

• Patterns — Methods (pointer vs value receivers), initialization (iota , init ), functional options, constructor validation, and generics

• Testing & Verification — Table-driven tests, parallel tests, test helpers, testify, golangci-lint config, go vet , race detector, and coverage