Go Development Best Practices

Expert guidance for writing clean, idiomatic Go code following community standards from Effective Go, Go Code Review Comments, and Google's Go Style Guide.

What This Skill Does

This skill provides comprehensive instructions for AI coding assistants when working with Go projects. It ensures code follows idiomatic Go practices, proper naming conventions, effective error handling, safe concurrency patterns, and security best practices.

Instructions for AI Agent

When writing or reviewing Go code, follow these principles and patterns:

General Principles

1. **Write simple, clear, and idiomatic Go code**

- Favor clarity and simplicity over cleverness

- Follow the principle of least surprise

- Keep the happy path left-aligned (minimize indentation)

- Return early to reduce nesting

- Make the zero value useful

2. **Documentation**

- Document all exported types, functions, methods, and packages

- Start comments with the name of the thing being described

- Package comments should start with "Package [name]"

- Document why, not what, unless the what is complex

3. **Dependency Management**

- Use Go modules (`go.mod` and `go.sum`)

- Keep dependencies minimal

- Regularly update dependencies for security patches

Naming Conventions

**Packages:**

Use lowercase, single-word names

Avoid underscores, hyphens, or mixedCaps

Choose descriptive names (not generic like `util` or `common`)

Use singular form, not plural

**Variables and Functions:**

Use mixedCaps or MixedCaps (camelCase)

Keep names short but descriptive

Exported names start with capital letter

Unexported names start with lowercase

Avoid stuttering (e.g., use `http.Server` not `http.HTTPServer`)

**Interfaces:**

Use -er suffix when possible (`Reader`, `Writer`, `Formatter`)

Single-method interfaces named after the method

Keep interfaces small and focused

**Constants:**

Use MixedCaps for exported, mixedCaps for unexported

Group related constants using `const` blocks

Use typed constants for type safety

Code Style and Formatting

**Formatting:**

Always use `gofmt` to format code

Use `goimports` for import management

Add blank lines to separate logical groups

**Comments:**

Write in complete sentences

Use line comments (`//`) for most cases

Use block comments (`/* */`) mainly for package docs

**Error Handling:**

```go

// Check errors immediately

result, err := doSomething()

if err != nil {

return fmt.Errorf("failed to do something: %w", err)

}

// Create custom error types when needed

type ValidationError struct {

Field string

Err error

}

func (e *ValidationError) Error() string {

return fmt.Sprintf("validation failed on %s: %v", e.Field, e.Err)

}

// Use errors.Is and errors.As for checking

if errors.Is(err, ErrNotFound) {

// handle not found

}

```

Architecture and Project Structure

**Package Organization:**

Follow standard Go project layout

Keep `main` packages in `cmd/` directory

Put reusable packages in `pkg/` or `internal/`

Use `internal/` for packages that shouldn't be imported externally

Avoid circular dependencies

**Dependency Management:**

Use `go mod tidy` to clean unused dependencies

Vendor only when necessary

Type Safety and Language Features

**Type Definitions:**

Define types to add meaning and safety

Use struct tags for JSON, XML, database mappings

Prefer explicit type conversions

Check second return value in type assertions

**Pointers vs Values:**

Use pointers for large structs or when modification needed

Use values for small structs and immutability

Be consistent within a type's method set

Consider zero value when choosing

**Interfaces and Composition:**

Accept interfaces, return concrete types

Keep interfaces small (1-3 methods ideal)

Use embedding for composition

Define interfaces close to usage, not implementation

Concurrency

**Goroutines:**

```go

// Always know how a goroutine will exit

ctx, cancel := context.WithCancel(context.Background())

defer cancel()

go func() {

for {

select {

case <-ctx.Done():

return

case work := <-workChan:

process(work)

}

}()

// Use WaitGroup for coordination

var wg sync.WaitGroup

for i := 0; i < workers; i++ {

wg.Add(1)

go func() {

defer wg.Done()

doWork()

}()

}

wg.Wait()

```

**Channels:**

Use channels to communicate between goroutines

Close channels from sender side

Use buffered channels when capacity known

Use `select` for non-blocking operations

**Synchronization:**

Use `sync.Mutex` for protecting shared state

Keep critical sections small

Use `sync.RWMutex` for many readers

Prefer channels over mutexes when possible

Use `sync.Once` for one-time initialization

Testing

**Test Organization:**

```go

// Table-driven tests

func TestParseURL(t *testing.T) {

tests := []struct {

name string

input string

want *URL

wantErr bool

}{

{

name: "valid http url",

input: "http://example.com",

want: &URL{Scheme: "http", Host: "example.com"},

{

name: "invalid url",

input: "://invalid",

wantErr: true,

}

for _, tt := range tests {

t.Run(tt.name, func(t *testing.T) {

got, err := ParseURL(tt.input)

if (err != nil) != tt.wantErr {

t.Errorf("ParseURL() error = %v, wantErr %v", err, tt.wantErr)

return

}

if !reflect.DeepEqual(got, tt.want) {

t.Errorf("ParseURL() = %v, want %v", got, tt.want)

}

})

}

// Test helpers

func setupTestDB(t *testing.T) *DB {

t.Helper()

db := createDB()

t.Cleanup(func() {

db.Close()

})

return db

}

```

Security Best Practices

**Input Validation:**

Validate all external input

Use strong typing to prevent invalid states

Sanitize data before SQL queries

Be careful with file paths from user input

**Cryptography:**

Use standard library crypto packages

Don't implement custom cryptography

Use `crypto/rand` for random numbers

Store passwords using bcrypt

Use TLS for network communication

API Design

**HTTP Handlers:**

```go

// Simple handler

func handleGet(w http.ResponseWriter, r *http.Request) {

if r.Method != http.MethodGet {

http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)

return

}

data, err := fetchData()

if err != nil {

http.Error(w, "Internal error", http.StatusInternalServerError)

return

}

w.Header().Set("Content-Type", "application/json")

json.NewEncoder(w).Encode(data)

}

// Handler with state

type Handler struct {

db *sql.DB

}

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {

// implementation

}

```

Performance Optimization

**Memory Management:**

Minimize allocations in hot paths

Reuse objects when possible (consider `sync.Pool`)

Preallocate slices when size is known

Avoid unnecessary string conversions

**Profiling:**

Use built-in profiling tools (`pprof`)

Benchmark critical code paths

Profile before optimizing

Focus on algorithmic improvements first

Essential Tools

Run these tools regularly:

`go fmt`: Format code

`go vet`: Find suspicious constructs

`golangci-lint`: Comprehensive linting

`go test`: Run tests

`go mod tidy`: Clean dependencies

Common Pitfalls to Avoid

Not checking errors

Ignoring race conditions

Creating goroutine leaks

Not using defer for cleanup

Modifying maps concurrently

Confusing nil interfaces vs nil pointers

Not closing resources (files, connections)

Using global variables unnecessarily

Over-using empty interfaces (`interface{}`)

Not considering zero values

Usage Examples

**Example 1: Create a new HTTP service**

```

Create a RESTful API service with user CRUD endpoints following Go best practices

```

**Example 2: Refactor existing code**

```

Review this Go code and refactor it to be more idiomatic and follow best practices

```

**Example 3: Add concurrency**

```

Make this data processing function concurrent using goroutines and channels safely

```

**Example 4: Write tests**

```

Write table-driven tests for this validation function with good coverage

```

Constraints

Always apply `gofmt` formatting

File patterns: `**/*.go`, `**/go.mod`, `**/go.sum`

Prioritize simplicity and clarity over performance unless profiling shows a need

Follow standard library patterns and conventions

Don't create goroutines in library code unless documented

Always handle errors explicitly

Go Development Best Practices

Go Development Best Practices

What This Skill Does

Instructions for AI Agent

General Principles

Naming Conventions

Code Style and Formatting

Architecture and Project Structure

Type Safety and Language Features

Concurrency

Testing

Security Best Practices

API Design

Performance Optimization

Essential Tools

Common Pitfalls to Avoid

Usage Examples

Constraints

Reviews (0)