Skip to content

Go Coding Guidelines

Idiomatic Go

  • Write Go, not Java/C++. Keep interfaces small and implicit.
  • Prefer composition over embedding; use embedding only when it genuinely fits.
  • Use defer for resource cleanup immediately after acquiring the resource.
  • Goroutines and channels only when concurrency is truly needed.
  • Design types so their zero value is already usable.

Project Structure

  • Package names: short, lowercase, no underscores. Plural only for utility packages (bytes, strings).
  • Standard Go Project Layout:
  • cmd/ — entry points (one subdirectory per binary)
  • internal/ — non-exported code
  • pkg/ — exportable libraries (use sparingly)
  • One file per logical unit; filename in snake_case (e.g., order_repository.go).
  • Test files: *_test.go for unit tests, *_ct_test.go for component tests, *_it_test.go with the build constraint integrative for integrative tests (see testing.md).

Code Style

  • gofmt / goimports mandatory — never format manually.
  • Short variable names in narrow scope (i, err, r, w); descriptive names in wide scope.
  • Name return values only when it meaningfully improves readability.
  • Comments explain the why, not the what. No comments for obvious code.
  • All exported symbols have a GoDoc comment starting with the symbol name.

Naming

  • Functions with side effects: verbs (send, save). Pure functions: nouns (payload, hex).
  • Predicates: Is / Has prefix.
  • Type aliases for domain concepts: type Amount float64, type OrderNumber string.

Error Handling

  • Always handle errors — using _ for errors is forbidden.
  • Wrap errors with context: fmt.Errorf("open config file: %w", err).
  • Check sentinel errors with errors.Is; typed errors with errors.As.
  • Define a custom error as a struct with exported fields for its data (e.g. an id, a Code) and an Error() string method that formats them for display — the fields stay directly accessible via errors.As, not only inside the formatted string (see internal/domain/errors.go's ValidationError in the car-rental-orchestrator demo for the pattern).
  • panic only for unrecoverable startup failures (e.g., MustNew... constructors).
  • Error return is always last.

Interfaces and Dependencies

  • Define interfaces in the consuming package, not the implementing one.
  • Verify interface compliance at compile time: var _ MyInterface = (*myImpl)(nil).
  • Constructors return interfaces, not concrete types — unless the package is internal.

Modern Go (Prefer Where Applicable)

  • any instead of interface{}.
  • Generics (1.18+): use when type parameters genuinely simplify the code.
  • errors.Join (1.20+) for combining multiple errors.
  • Range over integers (1.22+): for i := range n { ... }.
  • slices / maps packages (1.21+) instead of manual loops.

Logging (zap)

  • Pass logger as *zap.SugaredLogger — never as a global variable.
  • Use named loggers for subsystems: log.Named("order-service").
  • Pass fields as key-value pairs; never interpolate into the message string.

Testing

  • Table-driven tests are the default for multiple input cases.
  • Call t.Parallel() in independent tests.
  • No time.Sleep — use channels or sync.WaitGroup.
  • Mock only at package boundaries; test internal logic directly.
  • Use testify/require for preconditions, testify/assert for assertions.
  • Structure test bodies with // GIVEN, // WHEN, // THEN.
  • BDD scenarios with Godog; include a sample .feature file and step definitions.
  • make coverage counts every test and scenario for every package of the module, by passing the module's packages to -coverpkg. A Godog scenario in test/bdd that reaches internal/usecase counts for internal/usecase. A scenario that starts the built executable starts one built with -cover, which writes into the same GOCOVERDIR.
  • The debug executable is build/<artifact>-debug, the release executable build/<artifact>.

Directives

  • Define interfaces in the consuming package; verify at compile time: var _ MyInterface = (*myImpl)(nil)
  • Constructors return interfaces, not concrete types (unless package is internal)
  • Always handle errors — using _ for errors is forbidden; wrap with context: fmt.Errorf("op: %w", err)
  • Define custom errors as structs with exported data fields plus an Error() string method — keep fields directly accessible via errors.As, not only inside the formatted string
  • Pass logger as *zap.SugaredLogger — never as a global variable
  • Table-driven tests are the default; call t.Parallel() in independent tests; no time.Sleep
  • Use testify/require for preconditions, testify/assert for assertions; BDD scenarios with Godog
  • Project layout: cmd/ for entry points, internal/ for non-exported, pkg/ for exportable
  • Use any instead of interface{}; use slices/maps packages (1.21+) over manual loops