doc: add guidelines for comment directives

[mvdan]

This issue shares some resemblance with #13560. It is about properly documenting a pretty widespread convention regarding comment text.

In Go, //go: is reserved for the Go toolchain. This is documented at https://golang.org/cmd/compile/.

It is unofficially encouraged that other Go tools use a similar "namespace" prefix for their comment directives. For example, //gccgo: or //llgo: for other compilers, //lint: for staticcheck, //go-sumtype: for another tool, and so on. See https://groups.google.com/g/golang-dev/c/r4rdPdsH1Fg/m/tNZazPenX5cJ, as well as those two tools or others for examples out in the wild.

I think we should more formally define what this format should look like, so that one can programmatically tell if a comment line is a directive. For example, one could imagine ^[a-z-]+: as a regular expression.

This would help tools which use directives be more consistent, as well as tools which want to inspect all comments and directives in source code. For example, gofumpt does this now, and it takes some effort to tell if a comment is a directive.

I don't really mind where this is documented, as long as it's somewhere relatively authoritative. The wording doesn't have to be strong - after all, a Go comment can contain any plaintext. But it should still encourage tools to follow the format, for the sake of consistency.

[bcmills]

CC @stevetraut

[marat-rkh]

Hey! Is there any progress on this one? If not, I would be happy to help with something. For example, collecting existing use cases and forming some kind of proposal based on them. I am from the GoLand team, and our users would definitely benefit from comment directives.

[ianlancetaylor]

There is a formal definition at #37974 (comment), which is implemented by isDirective in go/printer/comment.go and by isDirective in go/ast/ast.go.

This could now perhaps be documented at https://go.dev/doc/comment.

[findleyr]

Just encountered this via a user report in golang/vscode-go#2477. I agree that this should be better documented, and doing so at https://go.dev/doc/comment makes the most sense.

Given that this will elevate the directive comment convention to a standard that we will continue to support, does this issue need to be a proposal?

[mvdan]

@findleyr I guess that depends on whether or not we think this unwritten rule is already a standard across Go or not. My thinking is that it already is a standard in practice, but if we're not sure or if we want to play it safe, using a proposal sounds fine to me.

[findleyr]

@mvdan I agree this is borderline, but a formal definition of comment directives is likely to have significant impact on the ecosystem. Notably, in the past tools such as golangci-lint have used different syntax for comment directives, which gofmt subsequently broke. By documenting a standard, we are both committing ourselves to avoiding such breakage in the future, and implicitly endorsing the use of comment directives by tools outside of the standard Go toolchain. That seems worth escalating to the proposal committee.

[seankhliao]

We also had 2 other reports for //nolint which seems to have been the only one to use that format: #53835 #54349

[rsc]

As Ian pointed out, we decided on #43776 (comment).
We should document this better.

[rsc]

Removed from the proposal process.
This was determined not to be a “significant change to the language, libraries, or tools”
or otherwise of significant importance or interest to the broader Go community.
— rsc for the proposal review group

[gopherbot]

Change https://go.dev/cl/442516 mentions this issue: _content/doc/comment: document form of directive comments