Unifying special comments convention

[Gustavo Niemeyer]

[Russ Cox]
> Changing the spelling of " +" to "go:" has real costs and no real benefit.

So how about not changing from "+" to "go:" in the first place?

We have at least the following comment conventions with special
semantics, all unlike each other:

// #cgo
// +build
// go:generate
// import

Two of those are still in a proposal status. Instead of accepting that
we cannot change what's there, we might instead accept that we cannot
have the preferred prefix because we weren't thinking too far ahead,
and have:

// #cgo
// +build
// +generate
// +import

Which feels a lot more sane than the multitude of conventions we're
walking into.


gustavo @ http://niemeyer.net

[Aram Hăvărneanu]

// go: already exists, it's used for //go:nosplit and //go:noescape.

--
Aram Hăvărneanu

[Russ Cox]

FWIW, you spelled //go:generate wrong (no space), and you forgot //line, //go:noescape, //go:nointerface (disabled by default), and //go:textflag (in a pending CL by khr).

The convention we are putting forth is this: 

1) Directive comments begin with // but no ' ', to distinguish them visually from ordinary comments.

2) The word after // is of the form namespace:name, where the namespace prefix serves to distinguish different people's directives. 

We own //go: but others can take other prefixes. For example, if there was some juju-specific thing you could use //juju:thing. There is a parallel here with struct tags: originally you wrote "foo" but now you have to write `json:"foo"` so that multiple packages wanting to use tags can coexist.

The "// +" and "//line" form satisfy (1) but not (2). They're historical exceptions. That happens. We move on.

The #cgo comment is another exception but is very different from these. It usually happens inside a large /* */ comment, not as "// #cgo", and usually next to a bunch of #includes, where it fits in nicely.

Russ

[Russ Cox]

Aram is right - It's //go:nosplit not //go:textflag.

[Gustavo Niemeyer]

Okay, I hadn't realized that "go:" was already in use in generally
available functionality. So, in an attempt to consolidate in the
opposite direction:

1. Can we introduce support for //go:build, with the hope of
obsoleting +build at some future release (even if it is Go2)? The
implementation cost of doing so is minimal.

2. Can we use //go:import for the special tag being proposed for
defining the import path?

This would mean having:

// #cgo
//go:build
//go:generate
//go:import

--

gustavo @ http://niemeyer.net

[Russ Cox]

On Wed, Jul 2, 2014 at 10:43 AM, Gustavo Niemeyer <gus...@niemeyer.net> wrote:

1. Can we introduce support for //go:build, with the hope of
obsoleting +build at some future release (even if it is Go2)? The
implementation cost of doing so is minimal.

No. This is exactly what I replied to in the previous thread.

2. Can we use //go:import for the special tag being proposed for
defining the import path?

Maybe. David Symonds made that comment in the proposal thread. I haven't thought about it yet.

Russ

[Gustavo Niemeyer]

On Wed, Jul 2, 2014 at 12:09 PM, Russ Cox <r...@golang.org> wrote:
> On Wed, Jul 2, 2014 at 10:43 AM, Gustavo Niemeyer <gus...@niemeyer.net>
> wrote:
>>
>> 1. Can we introduce support for //go:build, with the hope of
>> obsoleting +build at some future release (even if it is Go2)? The
>> implementation cost of doing so is minimal.
>
> No. This is exactly what I replied to in the previous thread.

Your argument there is that it has "real costs and no real advantage",
so I'm trying to understand it. Supporting an alternative standard
spelling is very cheap, enables people to use and encourage the better
convention by choice, and we can easily tweak gofmt to reformat +build
as go:build appropriately (I can contribute the code for both). We
don't need to drop the old format anytime soon, as it's so cheap, but
I bet we'd soon see it pretty much unused just out of choice.

>> 2. Can we use //go:import for the special tag being proposed for
>> defining the import path?
>
> Maybe. David Symonds made that comment in the proposal thread. I haven't
> thought about it yet.

Okay, thanks for considering.


gustavo @ http://niemeyer.net

[Russ Cox]

On Wed, Jul 2, 2014 at 11:59 AM, Gustavo Niemeyer <gus...@niemeyer.net> wrote:

On Wed, Jul 2, 2014 at 12:09 PM, Russ Cox <r...@golang.org> wrote:
> On Wed, Jul 2, 2014 at 10:43 AM, Gustavo Niemeyer <gus...@niemeyer.net>
> wrote:
>>
>> 1. Can we introduce support for //go:build, with the hope of
>> obsoleting +build at some future release (even if it is Go2)? The
>> implementation cost of doing so is minimal.
>
> No. This is exactly what I replied to in the previous thread.

Your argument there is that it has "real costs and no real advantage",
so I'm trying to understand it. Supporting an alternative standard
spelling is very cheap, enables people to use and encourage the better
convention by choice, and we can easily tweak gofmt to reformat +build
as go:build appropriately (I can contribute the code for both). We
don't need to drop the old format anytime soon, as it's so cheap, but
I bet we'd soon see it pretty much unused just out of choice.

I enumerated the costs in my reply that prompted the creation of this thread. You only quoted the last line:

Changing the spelling would incur one or more of these costs: (1) there would be two ways to write exactly the same thing, (2) people would have to update their code, (3) using the new way would make a program not compatible with older versions of Go, (4) other tools looking for the old way would have to be updated.

Go is intended for programming at scale, with large code bases. These are real costs in large code bases. If at all possible, the rule is to avoid incurring them.

Occasionally there is an important justification for breaking the rule. For example, Go 1.3 introduced some effective restrictions on unsafe.Pointer (mainly, they have to hold pointers) that might trigger cost (2). However, making those restrictions do not incur any of the other costs, and they make possible the significant benefit of being able to grow the stack by moving it, which has much better performance characteristics than the old stack growth implementation.

Changing the spelling of " +" to "go:" has real costs and no real benefit.

Russ

[Gustavo Niemeyer]

We break _forwards_ compatibility with every small addition (a new
field, a new method, ...), but I agree that the benefit of the
proposed change is hard to argue for in that regard.

Thanks for discussing and explaining the POV.