In a Go package spread over several files, where does the package comment belong?

## The rule A **package comment** is the doc comment attached to the `package` clause. Like every Go doc comment it binds by adjacency: it is the comment block immediately preceding `package name`, with no blank line in between. ```go // Package console renders an interactive admin terminal for internal // services. It is intended to be embedded in operator tools that are run // by hand rather than by automation. package console ``` The conventional opening is the literal word `Package` followed by the package name, so the sentence still identifies itself when a directory listing of packages prints one synopsis line per package. ## One file, not all of them A Go package is a set of files in one directory, each of which repeats the same `package` clause. Only one of those files should carry the package comment. The documentation tools gather package documentation from every file in the package, so if three files each open with a paragraph, the reader gets all three concatenated in an order determined by file name rather than by your intent — an overview that reads like it was assembled by accident, and one that silently changes shape when somebody adds `aaa_helpers.go`. So: pick a file and keep the comment there. ## What doc.go is for For a small package, the natural home is the file that holds the main type — `session.go` for `package console`. But a good package overview grows: what the package is for, the two or three entry points, a short usage sketch, concurrency guarantees, a pointer at the examples. Once that is twenty lines of prose sitting on top of a source file, it pushes the actual code below the fold and every reader of `session.go` scrolls past it. The convention is a file called **`doc.go`** containing exactly two things: the package comment and the package clause. Nothing else — no declarations, no imports. ```go // Package console renders an interactive admin terminal for internal services. // // Create a session with NewSession and drive it until the operator quits. // A session owns the terminal it is given and is not safe for concurrent use. package console ``` What this buys you: - **A stable home.** Implementation files get split, renamed and merged; `doc.go` does not, so the package overview never has to move and never accidentally gets deleted along with a refactored file. - **Discoverability.** A contributor looking for "where do I document this package" finds a file whose name answers the question. - **Clean code files.** No source file opens with half a screen of prose. - **Platform independence.** Files carrying build constraints are excluded from builds for other platforms, and a package comment living in such a file disappears with it. A constraint-free `doc.go` is always compiled in, so the docs exist for every target. The cost is a file that contains no code, which occasionally surprises newcomers from languages where such a file would be meaningless. That is the whole trade, and it is why very small packages often skip it. ## Commands A `package main` also gets a package comment, and there it documents **the command**: what the binary does, its flags, its exit behaviour. The convention is to lead with the command name — `// Consolectl runs an interactive admin console against a service.` — and this comment is precisely what a reader sees when they look the command up, since a command exports nothing else worth reading. ## What belongs in it Think of it as the front page a stranger lands on: what problem the package solves, the one or two calls that get them started, any rule they must obey ("the caller must close what New returns", "a Session is not safe for concurrent use"), and where to look next. What does not belong: change logs, TODO lists, internal design debates, and API reference material that should be on the individual declarations instead. If a paragraph is really about one function, it belongs on that function, where the reader will be standing when they need it. ## Checking it Read what you wrote the way a user will, with `go doc` on the package. Prose that looked fine as a block of `//` lines in an editor sometimes turns out to have lost its paragraph breaks or run its list lines together, and reading the rendered form is the fastest way to notice.