Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: guidelines for comment directives #43776

Open
mvdan opened this issue Jan 19, 2021 · 1 comment
Open

doc: guidelines for comment directives #43776

mvdan opened this issue Jan 19, 2021 · 1 comment

Comments

@mvdan
Copy link
Member

@mvdan mvdan commented Jan 19, 2021

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants