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

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

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) {

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

Full code examples: resources/types-functions.md

Functions

Full code examples: resources/types-functions.md

Data Types

new vs make

Slices

Maps

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

Methods

Pointer vs Value Receivers

* 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

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

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).

Full code examples: resources/patterns.md

Constructor & Validation

Full code examples: resources/patterns.md

Generics (Go 1.18+)

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

Testing

Full code examples: resources/testing-verification.md

Static Verification

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

Anti-Pattern Quick Reference

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.

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

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

Test File Placement

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