> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/languages/go/go-code-comments.md).

# Go: code comments

The Go form of doc comments, package comments and file comments.

Owner: Jeremy

A good comment in Go is whatever the Go standard library does. We find the most similar situation there and write the same comment, at the same length.

This page only adds the Go form. What a doc comment and an inline comment are for is on [Code comments](/engineering/development-process/how-to-build/coding-standards/code-quality/code-comments.md), for every language.

## Rules

* A doc comment is about as long as the doc comment on the most similar declaration in the standard library.
* Every package has a package comment. A large package puts it in its own `doc.go`.
* Methods of a well-known interface, such as `Error()` or `String()`, can go without a doc comment.

## Copy the standard library

**Find the most similar situation in the standard library and do the same.** That covers the comment, the shape of the API and the names. [Readability](/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md#make-the-code-explain-itself) describes where to look when the standard library has nothing similar.

**Copy the length too.** Comments that an LLM writes tend to be much longer. In the standard library, the median doc comment on an exported function is three lines long, and on an exported type two lines. If yours is several times longer than the most similar one, change the code or the comment.

**Methods of a well-known interface can go without a doc comment.** In `strings`, `bytes` and `time`, every exported function has a doc comment. Most exceptions elsewhere are methods such as `Error()`, `String()` or `Read()`. The interface already says what they do.

## Package comments

**The package comment says what the package is about.** It starts with "Package" and the package name, as [Go Doc Comments](https://go.dev/doc/comment#package) describes. It is written for a reader who knows none of the package's terms yet. A large package, such as `fmt` or `net/http`, keeps its package comment in its own `doc.go` file.

## File comments

**A file whose concepts are new to the reader can open with one line.** Go's documentation tools do not show such a line. The standard library still uses a short line after the license in about one file in six. Examples are "This file implements Sizes." and "DNS client: see RFC 1035." The line is for the engineer who opens the file.

## Named results

**A result that needs a comment to explain it can get a name.** A function returning a bare `bool` that a comment had to explain is clearer with [named result parameters](https://go.dev/wiki/CodeReviewComments#named-result-parameters), or with a small type.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/languages/go/go-code-comments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.