Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
proposal: cmd/gofmt: write official spec for gofmt #18790
In light of #18782 I would like to resurface an older discussion about the specifications for gofmt being provided as official specifications.
changed the title from
Official spec for gofmt
proposal: official spec for gofmt
Jan 26, 2017
I fear that an exact specification of gofmt might be more complex than the actual source. There are many heuristic decisions in gofmt (for instance when and when not to break alignment of comments in a long sequence of key:value pairs of map composite literals, etc.) which are relatively easy to express programmatically, but rather problematic in prose.
That said, I agree that gofmt has grown organically and at this point could use a clean rewrite, which might in fact be that specification.
(I've been working on such a rewrite on and off; perhaps it's time to focus on it a bit more diligently.)
A spec seems unnecessarily rigid. Gofmt is not a compiler, and we expect gofmt output to drift slightly over time as we fix problems. The underlying failure in #18782 seems to be that the CI system reports a test failure if code is not gofmt'ed correctly. A spec will not fix that: gofmt output will still change in minor ways over time.
@rsc maybe specifications is the wrong word here and I should have used: "set of rules".
And yes, many people run this against their repositories as part of their CI pipeline but if you don't touch a file you normally don't have a reason to format it so a break in CI like that will come from nowhere. I'm going to save the speech about the importance of gofmt for the Go community but if it continues to slowly drift, as you've said, we might just as well have the rules updated as well when that happen to understand the changes to it.
I've sadly tried many times to come up with the rules myself, by reading the current implementation, but this proved to be a rather hard task which lead nowhere. I definitely appreciate @griesemer's intention to refactor this into a cleaner implementation, maybe that's the best first step to do in this case.
That's exactly why a mis-formatted file should not break CI.
At Google, we use a presubmit check on the way into the repo, but if we adjust something in gofmt, our CI system doesn't break due to all the existing files. That's really untenable, and I would strongly suggest not doing that. Among other things, if gofmt changes slightly from say Go 1.7 to Go 1.8, it means your CI system can't support testing against both. (It's a good example of a forced atomic code repair.)
If you care a lot that files in the repo match a particular version of gofmt after being submitted, a better approach would be to have an automated process that checks in reformatted files as needed, without bothering people.
@mvdan The compiler (cmd/compile) already generates a new syntax tree during parsing (cmd/compile/internal/syntax) and that package also contains a printer. That printer is very basic at the moment, but there are hooks to make it more complete (hooking up comments with nodes so that they are printed at the right places). That said, you should not stop on #16371; rewriting gofmt is not a priority at this point. If it happens it happens, but it will have to be as close to the existing gofmt as we can make it (for a start at least), and everything that we fix in gofmt will serve as guideline for any future implementation.
referenced this issue
Nov 7, 2017
I'd like to offer an alternative use-case for having an official, human-readable spec for gofmt.
We are looking at using Go to built certified voting systems that conform with the VVSG (VOLUNTARY VOTING SYSTEM GUIDELINES). Despite the name, these guidelines are anything but voluntary in most US States.
Section 5.2.3 of VVSG 1.1 is as follows:
As it currently stands, the lack of a gofmt specification seems to be the only thing in our way to using Go as a VVSG compliant programming language. I'm sure that the VVSG isn't the only standard for critical software that requires documented, human-readable specifications for formatting standards.
Note that I think we could gloss over some of the more complicated logic that gofmt performs with generic phrases such as "Formatted code MAY opt to align comments in order to improve legibility" (for example).