Formatting and Inspection Tools

Every other language holds a formatting referendum: spaces or tabs, brace style, where the commas go. Teams write style guides, reviewers request re-indentation, and merges conflict over whitespace. Go's answer was to hand the question to a program.

gofmt reads any Go file and emits the one canonical layout — tabs for indentation, one statement per line, declarations spaced by the standard rules, comments realigned to what they document. It has no configuration: no style flags, no line-length limit (Go code routinely runs past 100 columns because the formatter refuses to break lines for width alone), and no opinions about your naming. What it has instead is three modes:

gofmt -l .       # list files whose formatting differs — print, change nothing
gofmt -d main.go # show the diff it would apply
gofmt -w .       # rewrite files in place

The workflow these support is the whole point. During development, -l answers "is anything off?" with a file list, -d answers "what exactly?" with a reviewable diff, and -w answers "fix it." go fmt ./... is the package-level wrapper that runs gofmt -l -w across a pattern and prints the files it touched — convenient locally, wrong in CI, because CI should check rather than mutate: a job that reformats silently hides the change from review. The durable check is one line:

test -z "$(gofmt -l .)"   # exits non-zero if any file is unformatted

Wire that into the same pipeline that runs the tests, and formatting debates end permanently. Enable format-on-save in your editor and the check never fires at all.

Two clarifications prevent the usual disappointments. First, gofmt is not a linter — it will happily format buggy code into perfect alignment, which is why it sits alongside go vet below rather than replacing it. Second, it does not strip things you find redundant, redundant parentheses around an if condition included: the compiler accepts them and gofmt leaves them, while the convention across every Go codebase writes if ready { with none. For import management — sorting groups, adding missing imports, deleting unused ones — the companion tool is goimports, covered in Imports, goimports, and go mod tidy. The habit to install today is the one that scales: save → formatted, commit → formatted, CI → formatted is a property, not a review comment.

You are reading a function you have never used and want its contract — the parameters, the behavior, the failure cases — without leaving the terminal or opening a browser tab on possibly-the-wrong-version docs. Go ships the answer inside the toolchain:

go doc                    # package docs for the current directory
go doc fmt                # overview of package fmt
go doc fmt.Println        # one symbol: signature + doc comment
go doc -all net/http      # every documented symbol in the package
go doc -src fmt.Println   # the actual source of the declaration
go doc -u cache           # include unexported symbols too

The crucial fact about go doc is where its content comes from: it renders the doc comments attached to declarations in the source in front of you. There is no second copy of the documentation to update and no generated file to commit — the comment above func Parse in the standard library or in your own package is the manual. That closes a loop with Comments and Doc Comments: write the comment in the right place with the right first sentence, and every surface — terminal, editor hover, pkg.go.dev — inherits it. Write a vague one and go doc will faithfully render the vagueness.

Reading the flags as a ladder: the default shows a symbol's documentation plus a one-line summary of what sits beside it; -all widens to the full package listing; -src jumps from prose to implementation when the comment raises a question the code answers faster; -u opens up the internals when you are debugging inside the package rather than consuming it. One behavior trips up newcomers: in a package main program, go doc shows the package comment but hides the exported symbols unless you pass -cmd — the assumption being that a command's API is its command line, not its functions.

This makes the standard library readable at the depth you need, offline, at the exact version you are compiling against — a version-sensitive detail browser docs get wrong the moment your toolchain and the website diverge. Get in the habit of resolving API questions with go doc before writing an import: it takes two seconds and it is always right about your build.

The compiler's job is to prove your program is well-formed Go. It is deliberately blind to questions like "did you mean the verb you wrote?" — those belong to go vet, whose charter is printed by go help vet: report likely mistakes in packages. It runs analyses over your compiled code and flags patterns that are legal and almost certainly wrong.

The printf analysis is the famous one. This compiles without complaint:

fmt.Printf("user %d spent %s\n", name, amount)  // name is a string

Printf accepts ...any, so the type mismatch passes straight through the compiler — and surfaces at runtime as %!d(string=alice). go vet matches each verb against the corresponding argument's type and reports it before the program ever runs:

./report.go:14:2: Printf format %d has arg name of wrong type string

The analyses are worth knowing by name because they cluster around specific bug classes:

Each one is code that compiles, passes casual reading, and fails in production — exactly the gap between "valid Go" and "correct Go" that this tool exists to cover. Run it the way you run the compiler:

go vet ./...

Then note the integration you get for free: go test runs a vet subset — printf, stringintconv, atomic, and friends — automatically before executing tests. A test file with a broken format verb fails the test run without any CI configuration, which is why a green go test already means slightly more than you assumed.

The full ladder, stated plainly: the compiler proves the program is well-formed; go vet reports likely mistakes; external linters (staticcheck, golangci-lint) extend the same pattern with style and correctness checks beyond the standard set. Nothing here overlaps arbitrarily — vet deliberately stops where analysis gets expensive or opinionated. Keep gofmt -l and go vet ./... as two commands in the same CI step and you have the same gate a Go team uses in production. With tooling habits set, the rest of this roadmap is language: starting with the expressions everything else computes.