---
name: golang-style-9f91709c4012
description:
  Go conventions specific to this author. Use before writing or editing any Go
  (.go) file.
---

# Go conventions

Where this author deviates from, or tightens, idiomatic Go defaults.

## Errors and control flow

- Structure functions so the happy path flows straight down: handle each error
  and return early, then continue with the main logic. Main logic never nests
  inside an `if err == nil` branch.
- Only wrap errors with `%w` if the underlying error should be
  exposed.
- Define expected error conditions as package-level sentinel errors
  (`var ErrNotFound = errors.New("not found")`) and check them with
  `errors.Is`, not `==` or string matching.

## Go version

Your idea of "current Go" is frozen at your training cutoff and is usually out
of sync with the project in both directions. Before writing code, read the `go`
directive in `go.mod` and check `go version`, and target the lower of the two.

That drift cuts both ways:

- Newer than you know: a helper you are about to hand-roll may already exist in
  `slices`, `maps`, `cmp`, `testing`, or a package you have never heard of.
- Older than you assume: a feature you treat as ordinary may postdate the `go`
  directive and simply not build.

`go doc <pkg>` answers both, but only for the toolchain installed here. To ask
about the version the module actually targets, use the pkg.go.dev API — no auth,
GET only ([announcement](https://go.dev/blog/pkgsite-api), spec at
`https://pkg.go.dev/v1beta/openapi.yaml`):

```sh
# Which symbols does a stdlib package have at a specific Go version?
curl -s "https://pkg.go.dev/v1beta/symbols/slices?version=v1.21.0"

# Current Go release, and any release candidate in flight.
curl -s "https://pkg.go.dev/v1beta/versions/std"

# Third-party: latest version, and the symbols it declares.
curl -s "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp"
curl -s "https://pkg.go.dev/v1beta/symbols/github.com/google/go-cmp/cmp"
```

Release notes are not in the API — fetch https://go.dev/doc/go1.N for a
release's changes, or https://go.dev/doc/devel/release for the index.

## Formatting

- Maximum line length 120 characters. Break long signatures and `fmt.Errorf`
  calls one argument per line.
- Indent with tabs rendered 2 wide.
- Organize imports with `gci`.
- End documentation comments with a period sign.

## Comments

Every comment ends with a period, including inline ones inside a function body.

## Naming

Never shadow a predeclared identifier with a variable or parameter name — not
`new`, `len`, `make`, `copy`, `max`, `min`, `clear`, `any`, `error`, `string`,
or any other builtin function, constant, or type. Pick a descriptive name
instead: `length` over `len`, `dataCopy` over `copy`.

## Sage

If the project has a `.sage` folder (Sage is used), run tasks through the
Sage-generated Makefiles rather than invoking `go` directly.


---
Source attribution: fredrikaverpil
Original project: https://github.com/fredrikaverpil/dotfiles/blob/f7f0329b62954fa245c4f8a216960af2cad9f725/stow/shared/.claude/skills/golang-style/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2021 Fredrik Averpil

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: fredrikaverpil
Original project: https://github.com/fredrikaverpil/dotfiles/blob/f7f0329b62954fa245c4f8a216960af2cad9f725/stow/shared/.claude/skills/golang-style/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Backend Developer, Full-Stack Developer
Specialties: Backend
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 55fe264f9f519c93832cf7033f15b0fd4bfd43f56cefdbeff42fc9a8516a8486