go-coding-standards

Files (3)

• SKILL.md
• file-organization.md · references/
• receivers-and-tags.md · references/

SKILL.md (first lines)

# Go Coding Standards

Idiomatic Go conventions grounded in Effective Go, Go Code Review Comments, and production-proven idioms.
All code MUST pass `goimports`, `go vet`, and `staticcheck` (or `golangci-lint run`) without errors.

> Community default. A project skill or agent-config rule that explicitly
> supersedes `go-coding-standards` takes precedence over this one.

Detailed reference material, loaded on demand:

- `references/file-organization.md` — declaration grouping, file order,
  breaking long signatures.
- `references/receivers-and-tags.md` — receiver consistency and struct tag
  examples.

Read a reference file only when the summary below is not enough.

## 1. Import Ordering

Group imports in this order, separated by blank lines:

```go
import (
    // 1. Standard library
    "context"
    "fmt"
    "log/slog"
    "net/http"

    // 2. External packages
    "github.com/gorilla/mux"

    // 3. Internal/project packages
    "github.com/myorg/myproject/internal/service"
)
```

NEVER use dot imports. Use aliasing only to resolve conflicts.

## 2. Naming

Naming is owned by the go-naming skill: packages, stuttering, initialisms,
getters, receivers, error and test names. Two rules stay here because they
are about declarations: do not shadow predeclared identifiers (`len`,
`new`, `error`, `min`, `max`), and unexported package-level variables may
carry a `_` prefix (`_defaultTimeout`) when the codebase uses that
convention.

## 3. Variable Declarations

### Top-level
Use `var` for top-level declarations. Do NOT specify type when it matches the expression:

```go
// ✅ Good
var _defaultPort = 8080
var _logger = slog.Default()

// ❌ Bad — redundant type
var _defaultPort int = 8080
```

### Local
- Prefer `:=` for local variables.
- Use `var` only when zero-value initialization is intentional and meaningful.

```go
// ✅ Good — zero value is meaningful
var buf bytes.Buffer

// ✅ Good — short declaration
name := getUserName()
```

## 4. Struct Initialization

ALWAYS use field names, and omit zero-value fields unless they carry
meaning — positional literals break silently when fields are added or
reordered:

```go
// ✅ Good
user := User{Name: "Alice", Email: "alice@example.com"}

// ❌ Bad — positional
user := User{"Alice", "alice@example.com", 0}
```

## 5. Reduce Nesting

Handle errors and special cases first with early returns, so the happy
path stays at the left margin. Drop an `else` whose `if` already returns,
and prefer assign-default-then-override:

```go
// ✅ Good — guard clauses; no else
for _, v := range data {
    if !v.IsValid() {
        continue
    }
    if err := v.Process(); err != nil {
        return fmt.Errorf("process %s: %w", v.ID, err)
    }
}

a := 10 // default, then override
if condition {
    a = 20
}
```

## 6. Grouping and Ordering

- Group related `const` and `var` declarations in one parenthesized block.
- File order: constants and variables, constructors, exported methods
  (by importance, not alphabetically), unexported methods, helpers.
- Methods sit directly after the type they belong to.

## 7. Line Length

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills