go-proverbs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Go Proverbs: Question the Plan

Interrogate a plan or spec with the 19 Go proverbs before any code exists. The proverbs are cheap to apply at planning time and expensive to apply after implementation. A plan that survives them produces less code and fewer rewrites.

The proverbs come from Rob Pike's talk at Gopherfest SV 2015 ([video](https://www.youtube.com/watch?v=PAAkCSZUG1c), [list](https://go-proverbs.github.io/)). "Don't panic" comes from the [Go wiki](https://go.dev/wiki/CodeReviewComments#dont-panic). Each proverb below carries a timestamp into the talk.

## How to Run the Interrogation

1. Read the plan, spec, or design the user provides. If the user gives no context, ask for the plan.
2. Walk the catalog below. For each proverb, decide: does this plan create tension with it?
3. Keep only the proverbs that bite. Most plans trigger 3 to 6 proverbs. A report that cites all 19 buries the real risks.
4. For each proverb that bites, output the proverb, the specific part of the plan it challenges, and 1 to 3 pointed questions. Ask questions — do not lecture and do not rewrite the plan.
5. Close with the one or two questions that matter most. These are the questions that change the plan if the answer is wrong.

Pike said the proverbs can contradict each other, and that this is fine — sometimes one engineering decision is right, sometimes its exact opposite ([21:12](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=21m12s)). Treat them as lenses, not laws. When the user has a good answer to a question, the proverb is satisfied. Do not re-argue a decision the user has already defended.

## Output Format

```
## Proverbs that bite

### "<proverb>"
<what part of the plan this challenges, 1-2 sentences>
- <question>
- <question>

## The questions that matter most
1. <question>
2. <question>
```

## The Catalog

Meanings paraphrased from the talk transcript (Rob Pike, Gopherfest SV 2015, retrieved 2026-08-20).

### 1. Don't communicate by sharing memory, share memory by communicating ([2:48](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=2m48s))

Pass the address of a data structure on a channel. When the sender does not keep the pointer, only the receiver has access, so safe concurrency is inherent in the model. The proverb is about ownership transfer, not about channels being mandatory.

- After each hand-off in this plan, who owns the data? Can two goroutines still reach the same pointer?
- Where the plan uses a shared structure plus a lock, would ownership transfer remove the lock?

### 2. Concurrency is not parallelism ([3:42](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=3m42s))

Concurrency is a way to structure a program so it is easy to understand and scalable. Parallelism is only the simultaneous execution of goroutines. Beginners confuse the two.

- Is the concurrency in this plan a structure, or a speed hack? Does the structure still make sense on one core?
- If the goal is speed, is there a measurement that shows the serial version is too slow?

### 3. Channels orchestrate; mutexes serialize ([4:20](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=4m20s))

A mutex is fine-grained: it makes one thing happen at a time to one variable. Channels and goroutines arrange how the pieces of the whole program work together, as in the canonical select-for loop.

- Does the plan use a channel where it only guards one variable? A mutex is smaller.
- Does the plan use a mutex to coordinate program flow? That is orchestration — channels fit better.

### 4. The bigger the interface, the weaker the abstraction ([5:17](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=5m17s))

The three most important interfaces in the Go ecosystem (`io.Reader`, `io.Writer`, `interface{}`) average two-thirds of a method. Small interfaces get many implementations and become a powerful structuring plan. The culture of small interfaces matters more than implicit satisfaction.

- How many methods does each planned interface have? Which callers need all of them?
- How many implementations do you expect? An interface with one planned implementation is a speculative abstraction.
- Can the interface split into two smaller ones that compose?

### 5. Make the zero value useful ([6:25](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=6m25s))

`bytes.Buffer` and `sync.Mutex` work without a constructor. Zero values compose: a struct whose fields all have useful zero values is itself useful when declared. Constructors are fine, but every avoided constructor is less API.

- For each planned type: what happens when a caller writes `var x T` and uses it?
- Does the plan require constructors or `Init` calls that a useful zero value would remove?

### 6. interface{} says nothing ([7:36](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=7m36s))

The empty interface carries no information and forces no guarantees on the caller, so nothing is statically checked. Pike calls `map[string]interface{}` "names to meaningless objects". Sometimes it is necessary; it is overused.

- Where does the plan use `any`? What is the one method that captures the real requirement?
- Would a generic type parameter or a small interface give the same flexibility with static checks?

### 7. Gofmt's style is no one's favorite, yet gofmt is everyone's favorite ([8:43](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=8m43s))

The value is in consistency, not in the specific choices. Experienced Go programmers name gofmt as their favorite feature even though nobody likes its output.

- Does the plan invent a convention, format, or style where a standard tool or an established convention exists?
- Is any part of the plan a preference argument in disguise?

### 8. A little copying is better than a little dependency ([9:28](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=9m28s))

A small dependency tree makes programs compile faster and easier to maintain. `strconv` copies its own ~10-line `isPrint` instead of importing 150 KB of Unicode tables — and a test keeps the copy in agreement, so the test has the dependency but the package does not.

- For each planned dependency: how many lines of it does the plan actually use? Would copying those lines cost less than the dependency?
- If a copy drifts from its source, what catches it? (The strconv pattern: a test that compares.)

### 9. Syscall must always be guarded with build tags ([11:10](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=11m10s))

`syscall` is system-specific by design — that is the point. If the plan needs portable behavior, it is using the wrong package; use `os` or another portable layer.

- Which OS and architecture does each syscall-touching piece of the plan assume? Where are the build tags?
- Should this use `os` or `golang.org/x/sys` instead?

### 10. Cgo must always be guarded with build tags ([11:53](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=11m53s))

Same reason: C is not portable. A build failure on an unsupported platform is better than a binary that builds and then breaks at runtime.

- On which platforms must this build? What happens on the ones the C code does not support?

### 11. Cgo is not Go ([12:37](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=12m37s))

With cgo you give up memory safety, correctness guarantees, stability, and garbage collection. Pike: about ninety percent of "my runtime corrupted" reports inside Google turned out to be cgo or SWIG problems. Sometimes a C library deserves use rather than a rewrite — but it is a trap to reach for it early.

- Is there a pure-Go path, even a slower one? What exactly does the C library buy?
- Who debugs the crashes that Go tooling can no longer explain?

### 12. With the unsafe package there are no guarantees ([13:49](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=13m49s))

Code that uses `unsafe` can break on any release, and the Go team would like to break more of it than they do.

- Is there a measurement that justifies `unsafe` in this plan? What is the fallback when a release breaks it?

### 13. Clear is better than clever ([14:35](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=14m35s))

From s0up4200/skills, MIT.

More from s0up4200/skills