CODEWITHSUNDEEP
go
Bruce Adams
Bruce Adams

Reputation: 5589

what are the uses of semantic comments in Go?

By analogy with this question about tags I note that there are several uses of comments in go beyond pure commentary.

Examples:

Are there any others I've missed?

Is there a definitive list somewhere?

Some third party packages like gocontracts and go-swagger use them as well. How can they avoid conflicting with each other?

Upvotes: 4

Views: 2984

Answers (2)

Bruce Adams
Bruce Adams

Reputation: 5589

As noted comments are directives in go not just comments.

There is at the time of writing no definitive list. This as logged as an golang issue 28532.

Therefore I propose using this answer to make one.

Uses in the go core language and tools themselves:

  • go:generate can be used for code generation.
  • godoc uses the function name to indicate comments it should interpret
  • Examples - document the expected output of a test (thanks @Butuzov)
  • build constraints (starting with '// +build')
  • Import comments e.g. 'package math // import "path"'

Notable uses in third party packages

How can they avoid conflicting with each other?

If you are developing a tool that really needs to treat comments as attributes and wish to avoid conflict with other similar uses prefix your comments with a namespace like "{mytool}: "

There are some conscious attempts at namespacing. Magic comments built into go use the "go: " prefix as in "go:generate" (except where they don't)

go-swagger uses "swagger: "

However you still need to approach this with caution and check the list here or any other source you can find.

Also consider whether comments are the best or only approach rather than using functions instead. Compare for instance (gocontracts):

// SomeFunc ensures:
//  * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
    // ...
}

with (godbc)

func SomeFunc(x int) (result string) {
    godbc.Require(strings.HasSuffix(result,"smth");
}

Upvotes: 7

Oleg Butuzov
Oleg Butuzov

Reputation: 5395

Examples - Allow to test function for example output.

Copy/Paste from link above. 

package stringutil_test

import (
    "fmt"

    "github.com/golang/example/stringutil"
)

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}

Upvotes: 2

Related Questions