Go Coding Standards

Purpose

Progressive disclosure of Go coding standards for agents writing Go code.

Authoritative Source: docs/explanation/software-engineering/programming-languages/golang/README.md

Usage: Auto-loaded for agents when writing Go code. Provides quick reference to idioms, best practices, and antipatterns.

Prerequisite Knowledge

IMPORTANT: This skill provides OSE Platform-specific style guides, not educational tutorials.

You MUST understand Go fundamentals before using these standards. Complete the AyoKoding Go learning path first:

1. Go Learning Path - Initial setup, language overview, quick start guide (0-95% language coverage)
2. Go By Example - 75+ heavily annotated code examples (beginner to advanced patterns)
3. Go In the Field - 37+ production implementation guides (standard library first, framework integration)
4. Go Release Highlights - Go 1.18-1.25 features (generics, fuzzing, PGO, iterators, Green Tea GC)

What this skill covers: OSE Platform naming conventions, framework choices, repository-specific patterns, how to apply Go knowledge in THIS codebase.

What this skill does NOT cover: Go syntax, language fundamentals, generic patterns (those are in ayokoding-web).

See: Programming Language Documentation Separation for content separation rules.

Quick Standards Reference

Naming Conventions

Packages: lowercase, single word

• http, json, user, payment
• Avoid underscores

Types and Functions: MixedCaps

• Exported: UserAccount, CalculateTotal()
• Unexported: userAccount, calculateTotal()

Variables: Short names in limited scope

• i, j for loop counters
• r for reader, w for writer
• Descriptive names for package-level: defaultTimeout

Constants: MixedCaps (not UPPER_CASE)

• MaxRetries, DefaultTimeout

Modern Go Features (Go 1.18+)

Generics: Use for type-safe data structures

func Map[T, U any](slice []T, f func(T) U) []U {
    result := make([]U, len(slice))
    for i, v := range slice {
        result[i] = f(v)
    }
    return result
}

Error Wrapping: Use fmt.Errorf with %w

if err != nil {
    return fmt.Errorf("failed to process user: %w", err)
}

Struct Embedding: Use for composition

type User struct {
    BaseModel
    Name string
}

Error Handling

Explicit Error Returns: Always check errors

result, err := doSomething()
if err != nil {
    return fmt.Errorf("operation failed: %w", err)
}

Custom Error Types: Define for specific cases

type ValidationError struct {
    Field string
    Err   error
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed for %s: %v", e.Field, e.Err)
}

Error Wrapping: Preserve error chain

return fmt.Errorf("processing user %s: %w", userID, err)

Concurrency

Goroutines: Use for concurrent operations

go func() {
    // Concurrent work
}()

Channels: Use for communication

ch := make(chan Result, 10) // Buffered
ch <- result                // Send
result := <-ch              // Receive

Context: Use for cancellation and timeouts

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

Testing Standards

Table-Driven Tests: Preferred testing pattern

tests := []struct {
    name     string
    input    int
    expected int
}{
    {"positive", 5, 10},
    {"zero", 0, 0},
    {"negative", -5, -10},
}

for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        result := double(tt.input)
        if result != tt.expected {
            t.Errorf("got %d, want %d", result, tt.expected)
        }
    })
}

Test Helpers: Use t.Helper() for helper functions

func assertEqual(t *testing.T, got, want any) {
    t.Helper()
    if got != want {
        t.Errorf("got %v, want %v", got, want)
    }
}

Security Practices

Input Validation: Validate all external input

• Check bounds, formats, and types
• Reject invalid input early

SQL Injection: Use parameterized queries

rows, err := db.Query("SELECT * FROM users WHERE id = ?", userID)

Context Timeouts: Always set timeouts

ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

Comprehensive Documentation

Authoritative Index: docs/explanation/software-engineering/programming-languages/golang/README.md

Mandatory Standards (All Go Code MUST Follow)

1. Coding Standards - Naming conventions, package organization, Effective Go idioms
2. Testing Standards - Table-driven tests, testify, gomock, TestContainers, Godog
3. Code Quality Standards - golangci-lint, gofmt, staticcheck, go vet
4. Build Configuration - go.mod structure, Makefile patterns, CI/CD integration

Context-Specific Standards (Apply When Relevant)

1. Error Handling Standards - Error wrapping, sentinel errors, custom error types
2. Concurrency Standards - Goroutines, channels, context, race detection
3. Type Safety Standards - Generics, type parameters, constraints, type assertions
4. Performance Standards - Profiling with pprof, benchmarking, memory optimization
5. Security Standards - Input validation, injection prevention, crypto practices
6. API Standards - REST conventions, HTTP routing, middleware patterns
7. DDD Standards - Domain-Driven Design tactical patterns without classes
8. Dependency Standards - Go modules, version selection, replace directives
9. Design Patterns - Common Go patterns (functional options, interface design)

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development

References

• Go README
• Functional Programming