I think requiring the "// Code generated ... DO NOT EDIT." comment to be near the top of the file rather than anywhere, if it can be done, is a change that would benefit both humans and machines reading .go files.

I agree with the bullet points under rationale.

It also seems to me that this change wouldn't be too disruptive or too late, and hopefully people can chime in if they believe otherwise. There are not that many generators/generated files that'll need updating, and many will be "fixed" by the change anyway. There are likely more projects that haven't been updated to use the existing https://golang.org/s/generatedcode convention yet (either because they didn't get around to it yet, or they don't have a need for it), so they can just target the latest version of the convention when they get around to it.

I have a minor clarification question to understand an edge case around the proposed change better:

I think we should change the rule to match the new //go:build rules (#41184), namely that the comment must appear before the first non-blank line, non-comment text. /* */ comments before the // Code generated ... comment would be allowed.

How are whitespace characters meant to be treated? Such characters would be an unlikely situation, but I'm hoping the proposed convention is clear about it. It can happen primarily in non-gofmted files (e.g., a stray trailing space in a generated file, or someone evaluating all edge cases of this proposal). For example:

/* foo */  /* bar */
    
// Code generated by gen. DO NOT EDIT.

package foo

I tried reading the placement section in the //go:build draft design, https://go.googlesource.com/proposal/+/master/design/draft-gobuild.md#design-placement, which says:

The new rule would be:

“Constraints may appear in any kind of source file (not just Go), but they must appear near the top of the file, preceded only by blank lines and other // and /* */ comments. These rules mean that in Go files a build constraint must appear before the package clause.”

It seems like whitespace should probably be allowed too, but that text doesn't include it explicitly. Is it included implicitly or not at all?

Spaces and tabs before the magic line don't matter.
(Go eschews investing invisible text with importance.)

I think many people (myself included) likely believed this to already be the case (which is why so many generators make that mistake).

Here's a question: under the current system, if your generator was based off of a text/template stored in a seperate file, what would be the best way to handle this? would it be ignored as it isn't a go file?

Here's a question: under the current system, if your generator was based off of a text/template stored in a seperate file, what would be the best way to handle this? would it be ignored as it isn't a go file?

I understand that the convention defined as a result of proposal #13560 was meant primarily for .go source files, so a text/template stored in a separate file wouldn't be affected as long as it uses a different file extension. But if someone were to try to use the convention on a text/template file, they may get a false positive.

This is a good point to consider and potentially clarify.

It's likely reasonable to use the same convention for non-.go source files that are supported by the Go build system, but from what I can see, that was not really discussed (other than in #13560 (comment)) or considered in scope of #13560. See https://golang.org/cmd/go/#hdr-File_types, which currently says:

Files of each of these types except .syso may contain build constraints, but the go command stops scanning for build constraints at the first item in the file that is not a blank line or //-style line comment.

I don't think it's viable for the Go project to define a convention to mark generated files of any arbitrary type. For example, some programming languages may not support line comments, so requiring a line that begins with "//" cannot work everywhere.

I understand that the convention defined as a result of proposal #13560 was meant primarily for .go source files, so a text/template stored in a separate file wouldn't be affected as long as it uses a different file extension. But if someone were to try to use the convention on a text/template file, they may get a false positive.

I think the most likely problem scenario would be someone using a text editor mode made for go files on a text/template file (that generated go code). The editor mode may assume that it would only be used on go source files, and thus complain about it. I don't think this (the scenario I laid out, not the issue as a whole) is a major issue though, just something to think about.

It's true that the primary focus for these comments is Go code and more generally Go package sources.
Go package sources today can be Go, assembly, C, C++, Objective C, SWIG, and Fortran.
The comment being discussed here, like the //go:build comment, handles all of these these except Fortran, which seems fine.

<Imagine snarky comment about "DO NOT EDIT" being implied by program being written in Fortran.>

Based on the discussion above, this seems like a likely accept.

No change in consensus, so accepted

Should this be closed?

@cristaloleg No. The proposal has been accepted, but it has not been implemented. At least, not as far as I know. For example, https://golang.org/s/generatedcode needs to point to the updated rule.

I updated golang.org/s/generatedcode to point to the relevant cmd/go docs.
I will also send a CL updating the cmd/go docs.

Change https://golang.org/cl/283633 mentions this issue: cmd/go: fix go generate docs