Go Standards

Go Standards

Core Rule: Use Go modules for dependencies, go test for testing, gofmt + go vet + golangci-lint for quality. Write idiomatic Go with explicit error handling.

When to use this skill

• When creating or managing Go modules and dependencies
• When writing or running tests in Go projects
• When formatting Go code or fixing linting issues
• When implementing error handling patterns
• When organizing package structure
• When deciding whether to create a new Go file or extend existing ones
• When setting up code quality checks (formatting, vetting, linting)
• When ensuring code follows Go idioms and best practices

Module Management

Use Go modules for all dependency management:

# Initialize a new module
go mod init github.com/org/project

# Dependencies are added automatically via imports
# Then run tidy to update go.mod and go.sum
go mod tidy

# Update all dependencies
go get -u ./...

# Update specific dependency
go get -u github.com/pkg/name@latest

# Verify dependencies
go mod verify

# Clean module cache
go clean -modcache

Module file structure:

• go.mod - Module definition and direct dependencies
• go.sum - Cryptographic checksums for dependencies

Testing with go test

Run tests using standard go test:

go test ./...                              # All tests
go test ./pkg/...                          # Tests in pkg/ and subdirs
go test -v ./...                           # Verbose output (debugging only)
go test -short ./...                       # Skip long-running tests
go test -race ./...                        # With race detector
go test -cover ./...                       # With coverage summary
go test -coverprofile=coverage.out ./...   # Generate coverage file
go tool cover -html=coverage.out           # View coverage in browser

Test file naming: Tests go in *_test.go files alongside the code they test.

Test function naming: func TestFunctionName(t *testing.T)

func TestProcessOrder(t *testing.T) {
    order := Order{ID: "123", Amount: 100}
    result, err := ProcessOrder(order)

    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if result.Status != "completed" {
        t.Errorf("got status %q, want %q", result.Status, "completed")
    }
}

Table-driven tests: Preferred for testing multiple cases:

func TestValidateEmail(t *testing.T) {
    tests := []struct {
        name    string
        email   string
        wantErr bool
    }{
        {"valid email", "user@example.com", false},
        {"missing @", "userexample.com", true},
        {"empty", "", true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := ValidateEmail(tt.email)
            if (err != nil) != tt.wantErr {
                t.Errorf("ValidateEmail(%q) error = %v, wantErr %v", tt.email, err, tt.wantErr)
            }
        })
    }
}

Code Quality Tools

Formatting with gofmt:

gofmt -w .           # Format all Go files in place
gofmt -d .           # Show diff without modifying
goimports -w .       # Format + organize imports

Static analysis with go vet:

go vet ./...         # Check for common mistakes

Comprehensive linting with golangci-lint:

golangci-lint run              # Run all enabled linters
golangci-lint run --fix        # Auto-fix where possible
golangci-lint run --fast       # Quick check (fewer linters)

Run quality checks before marking work complete.

Error Handling

Always handle errors explicitly. Never ignore them.

// REQUIRED - handle the error
result, err := doSomething()
if err != nil {
    return fmt.Errorf("doing something: %w", err)
}

// FORBIDDEN - ignoring errors
result, _ := doSomething()  // Never do this

Error wrapping: Add context when propagating errors:

func ProcessUser(userID string) error {
    user, err := fetchUser(userID)
    if err != nil {
        return fmt.Errorf("fetching user %s: %w", userID, err)
    }

    if err := validateUser(user); err != nil {
        return fmt.Errorf("validating user %s: %w", userID, err)
    }

    return nil
}

Custom errors: Use for domain-specific error types:

var ErrNotFound = errors.New("not found")
var ErrInvalidInput = errors.New("invalid input")

// Check with errors.Is
if errors.Is(err, ErrNotFound) {
    // handle not found
}

Code Style

Naming conventions:

Comments for exported functions:

// ProcessOrder validates and processes the given order.
// It returns ErrInvalidOrder if the order is malformed.
func ProcessOrder(order Order) error {
    // implementation
}

Import organization: Standard library, then third-party, then local:

import (
    "context"
    "fmt"
    "net/http"

    "github.com/gin-gonic/gin"
    "go.uber.org/zap"

    "github.com/myorg/myproject/internal/service"
)

Common Patterns

Context propagation: Always pass context as first parameter:

func ProcessRequest(ctx context.Context, req Request) (Response, error) {
    // Use ctx for cancellation, timeouts, and request-scoped values
    result, err := db.QueryContext(ctx, query)
    if err != nil {
        return Response{}, err
    }
    return Response{Data: result}, nil
}

Defer for cleanup:

func ReadFile(path string) ([]byte, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer f.Close()  // Guaranteed to run on function exit

    return io.ReadAll(f)
}

Struct initialization:

// Named fields (preferred for clarity)
user := User{
    ID:    "123",
    Name:  "Alice",
    Email: "alice@example.com",
}

// Zero values are valid - use them
var count int          // 0
var name string        // ""
var items []string     // nil (valid for append)

File Organization

Prefer editing existing files over creating new ones.

Before creating a new Go file, ask:

1. Can this fit in an existing package?
2. Is there a related file to extend?
3. Does this truly need to be separate?

Standard project structure:

project/
├── cmd/                  # Main applications
│   └── server/
│       └── main.go
├── internal/             # Private packages (can't be imported externally)
│   ├── handler/
│   ├── service/
│   └── repository/
├── pkg/                  # Public packages (can be imported)
│   └── api/
├── go.mod
└── go.sum

Verification Checklist

Before marking Go work complete:

• Code formatted: gofmt -w .
• Tests pass: go test ./...
• Static analysis clean: go vet ./...
• Linting clean: golangci-lint run
• All errors handled (no _ for errors)
• Dependencies tidy: go mod tidy
• Context propagated where needed
• Exported functions have comments

Quick Reference