swe-programming-golang

name	swe-programming-golang
description	Go coding standards quick reference for agents authoring Go code (primarily for downstream ose-primer; ose-public itself has no active Go apps)

Go Coding Standards

Purpose

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

Scope note: ose-public no longer ships a Go style-guide tree under docs/explanation/software-engineering/programming-languages/golang/ (Go was removed from active apps 2026-05-23; CLIs are now Rust). This skill is retained because swe-golang-dev authors Go for the downstream ose-primer template, which is the authoritative source for OSE Go conventions. Use the AyoKoding educational content below for universal Go idioms.

Educational Resource: AyoKoding Go Learning Path

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
2. Go By Example — 75+ heavily annotated code examples (beginner to advanced patterns)
3. Go In the Field — Production implementation guides (standard library first, framework integration)
4. Go Release Highlights — Go 1.18+ 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 (and in ose-primer).

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: Always %w for error args in fmt.Errorf — errorlint linter enforces:

if err != nil {
    return fmt.Errorf("failed to process user: %w", err) // %w preserves chain
}
// Never: fmt.Errorf("...%v", err) — errorlint violation

Error Comparison: Always errors.Is/errors.As — errorlint linter enforces:

if errors.Is(err, io.EOF) { ... }   // NOT: err == io.EOF

var exitErr *exec.ExitError
if errors.As(err, &exitErr) { ... } // NOT: err.(*exec.ExitError)

Sealed-Interface Sum Types: Use //sumtype:decl + gochecksumtype for exhaustive type switches:

//sumtype:decl
type MyStatus interface {
    isMyStatus()
    Code() string
    String() string
}
type StatusA struct{}
func (StatusA) isMyStatus()   {}
func (StatusA) Code() string  { return "a" }
func (StatusA) String() string { return "a" }

// gochecksumtype enforces exhaustive coverage:
switch s.(type) {
case StatusA:
    // ...
}

Doc Comments — godot + revive exported + revive package-comments enforce:

// Package doctor checks required development tools are installed.
package doctor

// Execute runs the root cobra command, writing errors to stderr and exiting on failure.
func Execute() { ... }

// DefaultMaxSize is the maximum allowed file size for env backup inclusion (1 MB).
const DefaultMaxSize = 1024 * 1024

// Code implements ToolStatus.
func (StatusOK) Code() string { return "ok" }

Rules:

• First line = identifier name + verb + object + period (godot)
• Imperative mood for functions: "Execute runs…" not "This runs…"
• Interface implementations: // Code implements [InterfaceName].
• String() (fmt.Stringer): optional — recognized as stdlib interface
• Unexported identifiers: no linter, code-review only
• Package main: // Package main is the entry point for [tool name].

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

OSE Platform Go standards now live in the downstream ose-primer template (authoritative for Go conventions in OSE-derived projects). ose-public itself has no active Go apps.

AyoKoding educational content (universal Go idioms — use for fundamentals and patterns):

• Go Learning Path
• Go By Example
• Go In the Field
• Go Release Highlights

Test-Driven Development

TDD is required for all Go code changes. Write the failing test first using Go testing (or a Godog step definition consuming a Gherkin scenario from specs/apps/<app-name>/), confirm it fails for the right reason, implement the minimum code to pass, then refactor. For Go CLI projects the primary levels are unit (Go testing + Godog, mocked I/O via package-level function vars) and integration (Godog //go:build integration + real /tmp filesystem). Property-based testing via gopter covers invariants over generated inputs.

Canonical reference: Test-Driven Development Convention

Related Skills

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

References

• AyoKoding Go Overview
• Functional Programming
• Programming Language Docs Separation