go-refactoring

Go Refactoring Workflow

A refactor changes structure, never behavior. The definition of done is mechanical: same tests pass before and after every step, and every step is small enough to revert alone.

1. The Loop

1. Baseline: go build ./... && go test ./... must be green before touching anything. If tests are missing around the target code, write characterization tests FIRST — they pin current behavior, even if that behavior looks wrong.
2. One transformation from the catalog below.
3. Verify: build + tests + go vet ./....
4. Commit. Never mix a refactor commit with a behavior change — reviewers can skim a refactor: commit; they must scrutinize a mixed one.
5. Repeat.

If step 3 fails and the fix isn't obvious in a minute, revert the step rather than debugging a half-applied transformation.

2. Renames — Let Tools Do Them

# Preferred: gopls (understands types, interfaces, embedding)
gopls rename -w internal/service/user.go:#offset newName

# Module path or package import path changes:
# update go.mod, then rewrite imports mechanically
find . -name '*.go' -exec sed -i 's|github.com/acme/old|github.com/acme/new|g' {} +
go build ./...   # the compiler is the reviewer

Never rename an exported identifier of a published library without a deprecation cycle: add the new name, mark the old one // Deprecated: use NewName., delete in the next major version.

3. Extract Package

Moving code out of a god package, in compiler-checked steps:

1. Create the new package; move one type and its methods (gopls or cut/paste), leaving everything else.
2. In the old package, add type aliases so nothing breaks: type User = user.User (aliases, =, not definitions).
3. Build. Migrate importers to the new path in batches; build each batch.
4. Delete the aliases when no importer remains.

This keeps every commit green with an arbitrarily large caller base.

4. Break a Circular Dependency

Packages a → b and b → a won't compile; near-cycles show up as god packages. Three escapes, in order of preference: