Godoc-Lint: a linter for Go Doc Comments (godocs) [RE#16]

I was in a break between jobs when I decided it’s time to tackle the idea I had for a long time; Godoc-Lint, a linter for Go Doc Comments (godocs). But before getting to Godoc-Lint, let’s talk about the problem.

Godocs and perfectionism

As a bit of context, Golang supports inline documentations (godocs), similar to JavaScript’s JSDoc or C#’s triple-slash comments (///). However, it’s much simpler/basic in features and structure. The thing is Golang (or gofmt to be more precise) does not enforce any restrictions on how to write godocs. That’s why Go developers usually drift off the style, almost unknowingly. For example, they may forget to document what a package does, or what a particular function is meant to be used for. It’s frustrating for the end users of their library/module to open up the browser and search the web or read the docs for their questions. Let alone the inconsistency that annoys those perfectionist maintainers of the project.

To see what I’m talking about, just imagine this simple file, foo.go:

// This package helps with a bunch of things.
package foo

// This prints a hey.
func Foo() {
    println("Hey")
}

At first sight, the it seems nicely documented with godocs. But in terms of standards and style, both godocs are not in a good shape. If we run the godoclint CLI, we’ll see why that is the case:

$ godoclint ./...
foo.go:1:1: package godoc should start with "Package foo "
foo.go:4:1: godoc should start with symbol name (pattern "((A|a|An|an|THE|The|the) )?%")

So the right use of godocs is something like this:

// Package foo helps with a bunch of things.
package foo

// Foo prints a hey.
func Foo() {
    println("Hey")
}

You’ll be amazed to see how many times people are breaking the godoc standard, which is well described in this official Golang document, Go Doc Comments.

Godoc-Lint

Godoc-Lint is now out to help with this issue. It comes with a number of predefined rules that aim to keep godocs consistent and in-style. To give it a try, you can download the CLI binary from the repo’s Releases page, or simply use the below go install command:

go install github.com/godoc-lint/godoc-lint/cmd/godoclint

Once installed, you can navigate into your Golang project directory, and run it like this:

godoclint ./...

This will run the linter on all packages in your project, with a sensible (i.e., less annoying, yet important) set of default rules. For more about the rules and configuration check out the repo’s README.

ℹ️ Note that on large code bases, when running godoclint for the first time it might take a bit, but further runs will be much faster.

---

About Regular Encounters

I’ve decided to record my daily encounters with professional issues on a somewhat regular basis. Not all of them are equally important/unique/intricate, but are indeed practical, real, and of course, textually minimal.