Google Go Style — Skill

Derived from the Google Go Style Guide, © Google LLC, licensed CC-BY 3.0. This skill is a derivative digest, not a verbatim reproduction.

Codifies the Google Go Style Guide (canonical + normative + best-practices) into actionable rules.

The full guide is large. This file holds only what should be in your head on every Go change. For deeper rules, load the matching

references/*.md

. For unusual situations, WebFetch the source — the guide is normative.

Quick Rules

Apply on every line of Go you write or review.

Naming

No
Get
prefix on getters.
```
User()
```
, not
```
GetUser()
```
. Exception: the underlying concept is "get" (HTTP GET).
Don't repeat the package name in identifiers.
```
bytes.Buffer
```
, not
```
bytes.BytesBuffer
```
.
```
widget.New
```
, not
```
widget.NewWidget
```
.
Receiver names: 1–2 letters, abbreviation of the type, consistent across all methods. Never
```
this
```
,
```
self
```
,
```
me
```
, or
```
_
```
(unless unused).
```
func (c *Config)
```
, not
```
func (config *Config)
```
.
Initialisms keep one case.
```
URL
```
,
```
ID
```
,
```
HTTP
```
,
```
DB
```
. Exported:
```
UserID
```
,
```
ServeHTTP
```
. Unexported:
```
userID
```
,
```
urlPath
```
. Never
```
Url
```
,
```
Id
```
,
```
Http
```
.
Test doubles end in
Stub
/
Fake
/
Spy
/
Mock
(or describe behaviour:
```
AlwaysCharges
```
,
```
AlwaysDeclines
```
).
No
util
/
common
/
helper
/
model
package names. They invite import renames at every call site. Name by what the package provides.
No underscores in identifiers (except
```
*_test.go
```
test/benchmark/example names, and packages imported only by generated code).
Local variable scope ↔ name length.
```
i
```
,
```
c
```
,
```
db
```
for tight loops;
```
userCount
```
,
```
pollInterval
```
for file scope. Don't drop letters to save typing (
```
Sandbox
```
, not
```
Sbx
```
).

Errors

fmt.Errorf("doing X: %w", err)
— wrap with
```
%w
```
at the end, so the chain prints newest→oldest as
```
outer: middle: inner
```
.
%w
only when callers need
errors.Is
/
errors.As
on the underlying error. Otherwise use
```
%v
```
.
%w
at the start is for sentinel wrappers only:
```
fmt.Errorf("%w: invalid header", ErrParse)
```
. Category first, details after.

Sentinel name:
ErrFoo
at package level:

var ErrNotFound = errors.New("not found")

Don't duplicate context the underlying error already carries.
```
os.Open
```
errors already include the path —
```
fmt.Errorf("could not open settings.txt: %v", err)
```
is wrong; use a higher-level annotation:
```
fmt.Errorf("launch codes unavailable: %v", err)
```
.
Don't add bare "failed: %v" wrappers. They add no information; just
```
return err
```
.
Either log it or return it — not both. Pick one. Letting the caller log avoids spam.

Error strings: lowercase, no trailing punctuation, no
\n
.

fmt.Errorf("something bad happened")

, not

"Something bad happened."

Cross-process boundaries (gRPC/RPC): use canonical codes via
```
status.Errorf(codes.X, ...)
```
rather than wrapping internal errors raw with
```
%w
```
.
error
is the last return value. A function taking
```
context.Context
```
should usually return
```
error
```
.

For more, see

references/errors.md

Panics

Don't panic for normal error handling. Return
```
error
```
and multiple return values.
log.Fatal
over
panic
for terminal conditions in
```
main
```
/
```
init
```
. Fatal does not run deferred functions; that's the point.
Panics never cross package boundaries in public APIs. Convert to
```
error
```
at the API edge with a top-level
```
defer recover()
```
that re-panics on unknown payloads.
MustX
is for package-level vars and tests only.
```
MustParse
```
,
```
template.Must
```
. Not for runtime user input.
Don't
recover()
to suppress crashes. Corrupted state propagates further; better is monitoring + crash + fix.
panic("unreachable")
after
log.Fatalf
is the idiom — the compiler doesn't know
```
Fatal
```
doesn't return.

For more, see

references/panics.md

Tests

No assertion libraries / helpers (

assert.Equal

require.NotNil

). Use

if got != want { t.Errorf(...) }

. For complex types:

cmp.Equal

cmp.Diff

from

go-cmp

t.Error
over
t.Fatal
by default — keep going, report all failures in one run.
```
t.Fatal
```
only when continuing is meaningless (setup failed, cascading errors would mislead).
Inside
t.Run
subtests: use
t.Fatal
to skip just that case. Outside subtests in a table loop:
```
t.Error
```
+
```
continue
```
.
NEVER call
t.Fatal
(
FailNow
,
Fatalf
,
SkipNow
) from a goroutine other than the test's own. Use
```
t.Error
```
from worker goroutines;
```
t.Fatal
```
only after
```
wg.Wait()
```
from the main goroutine.
Table-driven tests use named struct fields, not positional:
```
{name: "empty", input: "", want: ""}
```
.
Test helpers that fail setup call
t.Helper()
+
t.Fatalf
. This makes the failure point to the test line, not the helper line.
Failure message format:
YourFunc(%v) = %v, want %v
— function name, inputs, got, want, in that order.

For more, see

references/tests.md

Variables and strings

:=
for non-zero init,
var x T
for zero values.

i := 42

, but

var coords Point

(not

coords := Point{}

var t []string
, not
t := []string{}
for empty slices. Empty slice and nil slice behave the same for
```
len
```
,
```
cap
```
,
```
range
```
,
```
append
```
.
new(T)
vs
&T{}
: both are fine for zero values;
```
new
```
reads as "zero value placeholder",
```
&T{}
```
is more common when fields are filled.
Never
==
on
nil
for slices. Use
```
len(s) == 0
```
. APIs must not distinguish nil from empty.
Strings:
+
for 2–3 short literals;
fmt.Sprintf
for formatting;
strings.Builder
in loops;
text/template
for templates.
Pre-size with
make([]T, 0, n)
/
make(map[K]V, n)
only when
```
n
```
is known and the code is performance-sensitive. Default to zero-init.
No shadowing in nested scopes.
```
if *x { ctx, cancel := ...; }
```
shadows
```
ctx
```
outside the
```
if
```
. Use
```
ctx, cancel = ...
```
with
```
=
```
and
```
var cancel func()
```
declared above.

For more, see

references/strings-and-vars.md

API design

context.Context
is the first parameter.

func F(ctx context.Context, ...) error

. Even in test helpers.

Never store
context.Context
in a struct. Pass it through every method that needs it.
No global mutable state. Pass dependencies through constructors / function parameters (DI).
Take interfaces, return concrete types. The consumer of an interface defines it, not the implementer.
Channel direction in signatures.
```
<-chan T
```
for receive-only,
```
chan<- T
```
for send-only.
Many parameters → option struct (call site reads as labelled fields). 3+ optional / API expected to grow → option struct. Don't put
```
context.Context
```
in option structs.
Variadic functional options (
...Option
) only when most callers pass nothing, options need parameters, or third parties define options.
Avoid
*string
,
*io.Reader
parameters "to save bytes". Pass values; use pointers for large structs and protobuf messages.

For more, see

references/api-design.md

Documentation

Doc comments are full sentences starting with the symbol's name.
```
// Encode writes the JSON encoding of req to w.
```
Document WHY, not WHAT. The code already says what.
Document significant sentinel errors and error types the function returns.
Document cleanup contracts (
```
Close
```
,
```
Stop
```
, deferred resources).
Document concurrency-safety only when non-obvious (read-only methods are assumed safe; mutating ones are assumed unsafe — say so when that doesn't hold).
Don't document that
ctx.Done
cancels the function — that's the contract of
```
context.Context
```
.

For more, see

references/documentation.md

Package layout

internal/
for packages not part of the public API.
Avoid
util
/
common
/
helper
. Name by domain.
Imports grouped: stdlib / third-party / proto / blank-side-effect. Blank imports only in
```
main
```
or tests.
No
import .
ever (in Google codebase).
Proto imports get a
pb
suffix:
```
foopb "path/to/foo_go_proto"
```
.

For more, see

references/package-layout.md

Decision Matrices

%v

%w

when wrapping an error

Situation	Choose	Why
Caller will `errors.Is` / `errors.As` to inspect the chain	`%w`	Preserves type/sentinel through the chain
Crossing an external boundary (RPC, IPC, storage); caller wants canonical codes	`%v` (or `status.Errorf` )	Don't leak internal error types over the wire
Logging or human-display only; no programmatic inspection	`%v`	`%w` adds chain semantics nobody uses
Same error is logged here AND returned upward	`%v`	Wrapping a logged-then-returned error confuses the chain
Sentinel categorisation first ( `ErrParse` -style)	`%w` at start: `"%w: detail"`	Reader sees the category first
Adding context around a wrapped error (the common case)	`%w` at end: `"context: %w"`	Chain prints newest→oldest naturally: `outer: middle: inner`
Underlying error already carries this info	nothing — `return err`	Wrapping without adding info is noise
Just propagating without analysis	nothing — `return err`	Don't wrap for the sake of wrapping

Function arguments: positional vs option struct vs variadic options

Situation	Choose	Why
≤ 3 parameters, all required, all distinct types	Positional args	Smallest mechanism
Many parameters, most callers set most of them	Option struct (last param)	Self-documenting field names; grows without breaking call sites
Many parameters, most callers set none	Variadic options ( `...Option` )	Zero overhead at simple call sites
Options need failure validation	Variadic options returning `error`	Can't validate in struct construction
Third-party packages must define options	Variadic options with exported `Option` type	Struct fields can't be extended
Same option set used by multiple functions	Option struct	Reuse + share + write helpers on the struct
`context.Context`	First positional arg, never in option struct	Convention

panic

log.Fatal

error

return

Situation	Choose	Why
Library detects normal failure	`error` return	Caller decides
Library detects an "impossible" invariant violation	`error` return or `log.Fatal`	Caller can't recover anyway
Bad flag/config in `main` / `init`	`log.Exit` (no stack)	Stack trace useless; user wants the message
Internal package consistency check that has been verified by tests	`log.Fatal`	More reliable than `panic` (no defer deadlock risk)
Parser internals that always have a matching `recover` at the API edge	`panic` of a private type	Plumbing errors through deep recursion is noise
Package-level var initializer needs a value derived from a fallible call	`MustX` (panics)	Init-time only; `init` cannot return errors
HTTP handler crashes mid-request	never `recover()` to mask it	State is corrupted; let the process crash and restart

t.Error

t.Fatal

t.Errorf

continue

Situation	Choose
Multiple independent assertions in one `Test*` , all should run	`t.Error` / `t.Errorf` for each
Setup failure — rest of test cannot proceed	`t.Fatal` / `t.Fatalf`
First failure makes subsequent assertions misleading (e.g. encoded ≠ expected, can't decode meaningfully)	`t.Fatalf` then continue with `t.Errorf`
Table loop without subtests, this case is broken	`t.Errorf` + `continue`
Inside `t.Run(...)` subtest, this case is broken	`t.Fatal` (skips this subtest only)
Worker goroutine inside a test	`t.Errorf` only (NEVER `t.Fatal` )
Test helper called from main test goroutine	`t.Helper()` + `t.Fatalf` is fine

Variable declaration form

Situation	Choose	Example
Initializing with a known non-zero value	`:=`	`i := 42`
Need a zero value, ready for use	`var x T`	`var coords Point` , `var s []string`
Need a `*T` to a zero value	`new(T)` or `&T{}`	`msg := new(pb.Bar)`
Need a `*T` to a value with fields	`&T{...}`	`c := &Config{Port: 8080}`
Empty slice for return / accumulation	`var s []T`	not `s := []T{}`
Empty map (must be initialized to write)	`make(map[K]V)` or `map[K]V{}`	nil map can be read but not written
Pre-sized slice/map (perf-sensitive, size known)	`make([]T, 0, n)` / `make(map[K]V, n)`	Don't over-pre-allocate

Reference Files

Load on demand:

```
references/errors.md
```
— detailed error structure, wrapping rules, sentinels, RPC boundaries,
```
errors.Is/As
```
.
```
references/naming.md
```
— receivers, initialisms, repetition, test doubles, util-package antipattern, shadowing.
```
references/api-design.md
```
— option struct vs variadic options, channel direction, DI, interfaces, generics.
```
references/tests.md
```
— Test funcs vs helpers, table-driven, subtests, goroutines, acceptance testing,
```
cmp
```
.
```
references/panics.md
```
— when allowed (invariants, parsers with recover,
```
init
```
), when forbidden,
```
log.Fatal
```
vs
```
log.Exit
```
.
```
references/documentation.md
```
— godoc conventions, what to document, what to skip, contexts, errors, cleanup.
```
references/package-layout.md
```
— package size, file structure, imports,
```
internal/
```
, side-effect imports.
```
references/strings-and-vars.md
```
— concatenation choices, zero values, size hints,
```
new
```
vs
```
&T{}
```
, shadowing.

Authoritative Sources

When in doubt, especially for unusual situations, WebFetch the source section before writing the code. The Google Go Style Guide is the normative authority — this skill is a digest, not a replacement.

https://google.github.io/styleguide/go/index — overview, normativity definitions
https://google.github.io/styleguide/go/guide — canonical + normative core principles
https://google.github.io/styleguide/go/decisions — normative detailed decisions
https://google.github.io/styleguide/go/best-practices — non-normative patterns and discussions

For Go fundamentals not covered here, read Effective Go.

google-go-style

NPX Install

Tags

SKILL.md Content

Google Go Style — Skill

Quick Rules

Naming

Errors

Panics

Tests

Variables and strings

API design

Documentation

Package layout

Decision Matrices

`%v`
vs
`%w`
when wrapping an error

Function arguments: positional vs option struct vs variadic options

`panic`
vs
`log.Fatal`
vs
`error`
return

`t.Error`
vs
`t.Fatal`
vs
`t.Errorf`
+
`continue`

Variable declaration form

Reference Files

Authoritative Sources

google-go-style

NPX Install

Tags

SKILL.md Content

Google Go Style — Skill

Quick Rules

Naming

Errors

Panics

Tests

Variables and strings

API design

Documentation

Package layout

Decision Matrices

%v vs %w when wrapping an error

Function arguments: positional vs option struct vs variadic options

panic vs log.Fatal vs error return

t.Error vs t.Fatal vs t.Errorf + continue

Variable declaration form

Reference Files

Authoritative Sources

`%v`
vs
`%w`
when wrapping an error

`panic`
vs
`log.Fatal`
vs
`error`
return

`t.Error`
vs
`t.Fatal`
vs
`t.Errorf`
+
`continue`