uber-go/guide: the Uber Go Style Guide and the Makefile that builds it

What uber-go/guide actually contains

The repository holds the Uber Go Style Guide, which the README describes as documenting patterns and conventions used in Go code at Uber. That wording matters. This is a house style, written from the experience of one large Go codebase, not a neutral survey of the Go community's preferences. Where the guide takes a position, it takes it because Uber's code needed a decision, and the reasoning is usually stated alongside the rule.

The practical artifact is style.md at the repository root. The rest of the tree supports it: src/ holds the Markdown fragments, src/SUMMARY.md defines the order, src/preface.txt is prepended, and the Makefile regenerates style.md from those pieces. There is a CHANGELOG.md, a CONTRIBUTING.md, a CODE_OF_CONDUCT.md and a .golangci.yml, but no Go package that a reader would import. If you were hoping to add this as a dependency, there is nothing to import.

The audience is therefore narrow and specific. It is for Go engineers who review other people's code and need a shared vocabulary for arguments like whether an error should be wrapped, how a channel should be closed, or when a function should accept an interface. It is also for teams writing their own guide who want a worked example of one. It is not for someone who wants their editor to fix their code.

Why the guide is assembled by a Makefile instead of edited in place

The interesting engineering choice here is that style.md is generated. The Makefile installs a tool called stitchmd into a local bin/ directory and runs it with a fixed set of arguments:

STITCHMD = $(GOBIN)/stitchmd
STITCHMD_ARGS = -o style.md -preface src/preface.txt src/SUMMARY.md

stitchmd reads src/SUMMARY.md, follows the files it references, prepends the preface text, and writes the concatenated result to style.md. The target depends on the wildcard src/*, so editing any source fragment marks style.md as stale.

The payoff is reviewability. A pull request that adds a rule touches one small file in src/ plus a line in SUMMARY.md, and reviewers see a focused diff instead of a change buried in a thousand-line document. The cost is that style.md is a build output committed to the repository, which means it can drift. The Makefile anticipates exactly that with a lint target that runs stitchmd in diff mode and fails when the generated file does not match the sources. The comment in the Makefile says the options are kept in sync with .github/workflows/ci.yml, so the same check runs in CI.

That is a small but real piece of discipline. Most documentation repositories have no mechanism at all for detecting that the published file and its sources disagree.

Building style.md locally and reading it

The repository gives no installation instructions for the guide itself, because there is nothing to install. What it does give is the build path for the generated document, and that is the only command sequence worth running. You need Go on your PATH, since the Makefile shells out to go install.

make all

This installs stitchmd into bin/ via go install go.abhg.dev/stitchmd@latest and then regenerates style.md from src/SUMMARY.md with src/preface.txt as the preface. After it finishes, style.md at the repository root should be rewritten; if it was already current, the content will be unchanged.

To check that the committed style.md matches the sources without modifying anything, run the lint target. It computes a diff and prints it when the file is stale:

make lint

If the output is empty and the command exits successfully, the generated document is in sync. If style.md is out of date, the target prints the diff and fails, which is the same behaviour CI relies on. A first real use of the repository is simply reading style.md end to end, then opening the corresponding file under src/ when you want to quote a rule in a code review, so that you cite the maintained source rather than a copy.

The guide has no enforcement, and that is the main limitation

Nothing in this repository checks your code. There is a .golangci.yml at the top level, but the README does not present it as a supported way to enforce the guide, and the Makefile's only lint target validates the generated Markdown, not Go source. If you adopt the guide, the enforcement mechanism is your review process and whatever tooling you already run.

That gap shows up in practice. A rule that a human reviewer applies consistently is a rule; the same rule written in a document that nobody opens during review is decoration. The guide's value depends entirely on whether your team treats it as a reference during pull requests, which is a social arrangement, not a technical one.

A second limitation is scope. The guide documents conventions used in Go code at Uber, and Uber's constraints are not universal. A team of three people writing a small service may find some of the structure the guide assumes heavier than it needs. Reading it as a menu of defensible positions works better than reading it as a specification you must satisfy line by line.

A third is freshness. The last push to the repository was on 2026-04-15, and the most recent release listed is from 2023-05-09. The document moves slowly by design, but Go itself does not, so a rule that reflected the language as it was several years ago may need re-reading against the current toolchain before you cite it.

Translations, and the risk of quoting a stale copy

The README lists community translations into Chinese, Traditional Chinese, Korean, Japanese, Spanish, Thai, Portuguese (two variants), Polish, Russian, French, Turkish, Ukrainian, Persian, Vietnamese, Arabic and Indonesian, each linking to a separate repository. These are maintained by volunteers, not by Uber, and the README says only that the project is aware of them.

That is useful and worth being careful about. A translation is a fork of the text at a point in time. If the English style.md changes and the translation repository does not follow, a reader who cites the translated rule is citing something the upstream guide may no longer say. For a code review argument, that difference matters, because the other person can reasonably ask which version you are quoting.

The README also invites anyone with a translation to submit a pull request adding it to the list, so the list itself is a maintained index rather than a fixed set. If you work in a language that appears there, the translation is a reasonable way to get a first read of the guide's structure, but the English style.md is the source of truth for any rule you intend to enforce.

How this differs from Effective Go and the Go Code Review Comments

The obvious comparison is with the two documents most Go teams already point at: Effective Go, published by the Go project, and the Go Code Review Comments page on the Go wiki. Both are broader in authorship and deliberately avoid taking positions where the community has none.

The difference in approach is that Uber's guide is opinionated where the official documents are descriptive. Effective Go explains idioms and leaves the choice to you; the Code Review Comments page collects things reviewers commonly flag. Uber's guide says what Uber does, and the reasoning behind each choice is part of the text. That makes it more useful as a tiebreaker when your team cannot agree, and less useful as a neutral introduction to the language, because a newcomer reading it may mistake one company's convention for the language's requirement.

A second difference is the build. Effective Go and the wiki page are single documents maintained in place. This repository splits the content into src/ fragments and generates style.md, which is why the contribution workflow looks like a small software project rather than a documentation edit. If you want to fork the guide for your own team, that structure is the part worth copying: it keeps individual rules reviewable.

Maintenance, licence and what you are taking on

The repository is not archived. The last push was on 2026-04-15, and the releases listed are from 2022-10-18, 2023-04-13 and 2023-05-09. Releases are infrequent, which fits a document that changes by accumulating rules rather than by shipping features. The practical maintenance cost for a consumer is close to zero: you read the guide, you do not run it in production.

If you fork it, the cost changes. You inherit the src/ plus stitchmd pipeline, so contributors need Go installed to regenerate style.md, and CI needs the same lint target or the generated file will drift from its sources. The Makefile's lint target exists precisely to catch that, and it is the piece to copy first.

The licence is Apache-2.0, stated in the LICENSE file at the repository root. Apache-2.0 permits commercial use, modification and redistribution, and it includes an explicit patent grant, which matters more for a document you might embed in internal tooling than for one you simply read. It also requires that you preserve the licence and attribution notices when you redistribute the work or a derivative. None of this is legal advice, and if you plan to ship a modified version inside a product, the terms are worth reading in full rather than summarizing from a one-line description.

Editorial conclusion

Adopt uber-go/guide if you want a written, opinionated reference for Go review discussions and you accept that nothing in the repository enforces it. Do not adopt it expecting a linter, a config file, or a tool that fails your build; gofmt, go vet and a linter of your own choosing are separate decisions this project does not make for you. Before quoting a rule, open style.md at the section you intend to cite, check whether the guide states a general principle or an Uber-specific convention, and check whether a translation you are reading has drifted from the English original. The last push to the repository was on 2026-04-15, so treat the text as stable rather than fast-moving.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. uber-go/guide on GitHub