Go: proposal: cmd/go: introduce go.gen file for //go:generate comments

[andreynering]

The problem with //go:generate comments is that they are too "hidden" in the source code. You have to search the whole project for these comments in order to know what will happen when you run go generate ./....

This kind of thing should be centralized and easy to find. I propose that go generate should also run commands available on a go.gen file (this name is to follow the current convention of go.mod and go.sum). This file would look like this:

goyacc -o gopher.go -p parser gopher.y
stringer -type=Pill

(Examples extracted from the official go generate blog post). Each line is a separated command, there's no special syntax there. //go:generate comments should keep working, this is just an alternative way to define commands.

[AlexRouSg]

If your goal is to make the comments easier to find, why not a cmd/go arg to list all such comments? Also how is this better than just putting all your generate comments into a single file called gen.go?

[sagarkrkv]

A simple grep search viz., grep -r "go:generate" . can easily find and list all the go generate comments.

[ianlancetaylor]

Or we could encourage a convention of putting them in a file named gen.go. I'm not seeing a reason for go.gen.

[andreynering]

If your goal is to make the comments easier to find, why not a cmd/go arg to list all such comments?

That would definitely help, but still doesn't invalidate my proposal.

A simple grep search viz., grep -r "go:generate" . can easily find and list all the go generate comments.

That doesn't help if you're on Windows where grep is not available. Or if you're just navigating through an OSS project on GitHub (or similar).

---

@AlexRouSg @ianlancetaylor Yep, if gen.go was an encouraged convention, it'd do the trick!

I think I still see value on go.gen, though. It'd be more likely to be used than a different convention. And I don't see a reason to keep generate commands as comments inside source code, instead of in a proper place for it to be.

[bcmills]

go doc shows comments from the package source code. A go doc flag or argument to show the go:generate comments in particular would not seem out-of-place.

[rsc]

Note that if we change the convention, we can't get rid of the old one. We'll just have two conventions. That's typically not an improvement.

There is value in having all the go:generate lines in one place, and there is also value in having all the go:generate lines next to the things they are related to (like putting go:generate stringer lines next to the type they generate a String method for). Enforcing one is probably not right. If you want to use a gen.go, great.

We probably shouldn't force everyone, and we can't change all the existing usage even if we wanted to. I don't see how we can adopt this proposal at this point. Am I missing something?

[andreynering]

@rsc I do understand, specially since is this a very subjective proposal.

But what about the idea of a flag to show these comments as suggested here and here?

[sapk]

@andreynering You can list commands with go generate -n ./.... The command can maybe improved by displaying in what folder they are present (and executed).
go generate -v -n ./... list all the parsed files and when it found a command to execute.

[rsc]

Based on https://github.com/golang/go/issues/33375#issuecomment-518840747, it sounds like this is a likely decline (adds a second way to do something without being able to remove the first one; increased complexity). The only comment since then, by @andreynering, was answered by @sapk.

(Also, in all seriousness, one of the first things I do on a Windows box is find a way to install a grep implementation.)

Leaving open for a week for final comments.

[rsc]

Marked this last week as likely decline w/ call for last comments (https://github.com/golang/go/issues/33375#issuecomment-523192428).
Declining now.