Go Lang: Comments Are Not Directives

#1

Post by Merkur » Mon, May 11, 2015, 5:59 AM UTC

Go 1.4 starts to use comments as directives. I think that is a realy bad path to go on the long run. You see its beginnings in following 3 examples:

# used to set a canonical import path for a package: //import "foo"

# used to generate code: //go:generate bar

# used to document the result of a example function: //Output: foo

Comments should not be directives. Comments are free form, they do not have a syntax (as demonstrated in the examples). Comments are for humans - programms should ignore them or threat them as - comments!

It is my optinion that if Go needs some kind of annotation, than there should be a new syntax for it.

I would propose that directives to the tool chain will be marked with

#TAG: DIRECTIVE

a tool would be able to register the TAG with the go build environment. If a TAG is found in the code - the tool is called to do what ever needs to be done.

Re: Go Lang: Comments Are Not Directives

#2

Post by aikah » Mon, May 11, 2015, 6:44 AM UTC

I 100% agree. You want macros? I don't like it but think about proper macros. Go generate is just sweeping issues under the carpet and say to developers "it has been dealt with". Nobody expects a language to be perfect, but sometimes I feel the Go team takes devs for idiots with half baked solutions. So don't use comments for anything but documentation generation purpose.

.

Re: Go Lang: Comments Are Not Directives

#3

Post by enneff » Mon, May 11, 2015, 6:47 AM UTC

(You left out "// +build", which predates Go 1.4.)

We made the decision that "//go:" is the syntax for comment directives. The old ones stay around for compatibility reasons.

Previous discussion: https://groups.google.com/forum/#!searchin/golang-dev/commen...

Re: Go Lang: Comments Are Not Directives

#4

Post by enneff » Mon, May 11, 2015, 6:51 AM UTC

aikah wrote: post #2

I 100% agree. You want macros? I don't like it but think about proper macros. Go generate is just sweeping issues under the carpet and say to developers "it has been dealt with". Nobody expects a language to be perfect, but sometimes I feel the Go team takes devs for idiots with half baked solutions. So don't use comments for anything but documentation generation purpose. .

> Go generate is just sweeping issues under the carpet and say to developers "it has been dealt with", which is ,at the minimum, insulting. Nobody expects a language to be perfect, but sometimes I feel the Go team takes devs for idiots with half baked solutions.

That's absolutely a mischaracterisation, and a hurtful one at that because we absolutely care about our developer experience.

"go generate" is a mechanism for invoking code generation tools; tools that people were already using in a variety of ad hoc ways. That's all. Macros are another thing entirely.

Our conservatism should be a testament to how much we care about quality. We don't want to do anything by half measures, as that serves no one's interests.

Re: Go Lang: Comments Are Not Directives

#5

Post by bsaul » Mon, May 11, 2015, 6:51 AM UTC

Agree as well.

They could use the same convention as typescript and use a triple slash instead. That wouldn't change much of the language and impact IDEs, but at least distinguish between human comments and tooling instructions.

Re: Go Lang: Comments Are Not Directives

#6

Post by enneff » Mon, May 11, 2015, 6:52 AM UTC

bsaul wrote: post #5

Agree as well. They could use the same convention as typescript and use a triple slash instead. That wouldn't change much of the language and impact IDEs, but at least distinguish between human comments and tooling instructions.

What's the difference between "///" and "//go:"? The latter is Go's official convention, it's just that unfortunately some of our older mechanisms predate the convention.

Re: Go Lang: Comments Are Not Directives

#7

Post by aikah » Mon, May 11, 2015, 7:09 AM UTC

enneff wrote: post #4

aikah wrote: post #2

I 100% agree. You want macros? I don't like it but think about proper macros. Go generate is just sweeping issues under the carpet and say to developers "it has been dealt with". Nobody expects a language to be perfect, but sometimes I feel the Go team takes devs for idiots with half baked solutions. So don't use comments for anything but documentation generation purpose. .

> Go generate is just sweeping issues under the carpet and say to developers "it has been dealt with", which is ,at the minimum, insulting. Nobody expects a language to be perfect, but sometimes I feel the Go team takes devs for idiots with half baked solutions. That's absolutely a mischaracterisation, and a hurtful one at that because we absolutely care about our developer experience. "go generate" is a mechanism fo…

My apologies if I sounded a bit rough. I know and like your conservative approach and respect your work. I just think that's not a good feature, at all. Because once you start adding pragmas in comments, where does it stop? I'm a bit emotional about it because I love Go,I use it everyday and have been successful with it. If i didn't I wouldn't be writing about it.

Re: Go Lang: Comments Are Not Directives

#8

Post by TheDong » Mon, May 11, 2015, 7:17 AM UTC

Want to know what's even worse? Using comments for something but not parsing the syntax tree.

In go 1.4, save the following to a file and run 'go generate' on it: https://play.golang.org/p/9WJtxClRXr (I'd make it run in the playground, but you can't 'fork exec', so exec.Command($GOBIN, generate) won't work sadly)

Even though that code has no comments (only a multi-line string), go generate will run and print out a '\'.

I also used that generate command to point out that with generate, as it exists in 1.4, there's actually NO WAY to print out a dollar sign.

The dollar-sign part of this is fixed in master (so go1.5), but it was fixed not by allowing '\$', but by the bizarre $DOLLAR environment variable. See https://go-review.googlesource.com/#/c/8091/

These "features" make the use of comments as directives even worse, because it's NOT comments being used as directives in the case of go generate, but simple string matching. It literally just loops through lines of text and checks if it startswith the correct substring.

This was, of course, done due to lazyness (same as $DOLLAR and many other 'features' of go), and the lazyness is starting to show through the cracks here and there.

Go often prefers pain for the programmer for the compiler developer's life being simpler by about 5 minutes.

Re: Go Lang: Comments Are Not Directives

#9

Post by nulltype » Mon, May 11, 2015, 7:17 AM UTC

I don't really agree. I don't see any substantial difference between //go: and #go: except that programs using the # syntax would not build on older versions of go. I haven't really run across any issues with the current syntax. What kind of issues are you having?

Re: Go Lang: Comments Are Not Directives

#10

Post by TheDong » Mon, May 11, 2015, 7:19 AM UTC

enneff wrote: post #3

(You left out "// +build", which predates Go 1.4.) We made the decision that "//go:" is the syntax for comment directives. The old ones stay around for compatibility reasons. Previous discussion: https://groups.google.com/forum/#!searchin/golang-dev/commen...

Also 'cgo' comments which are fairly old. See: https://golang.org/cmd/cgo/

For an example of what this looks like in actual use, see the very popular go-sqlite3 library: https://github.com/mattn/go-sqlite3/blob/dee1a37fe11067e9797...

I personally think that large block-comments of code that actually do something, but only if above a certain import really strange and unexpected; it means re-ordering imports can break things, changing around spacing can break things, and tons of other things.