Go: all: reduce golint errors on standard library

[willfaught]

I was surprised to learn that the stdlib doesn't conform very well to golint. Example:

$ golint strings 
/usr/local/Cellar/go/1.9/libexec/src/strings/reader.go:47:1: exported method Reader.ReadAt should have comment or be unexported
/usr/local/Cellar/go/1.9/libexec/src/strings/reader.go:62:1: exported method Reader.ReadByte should have comment or be unexported
/usr/local/Cellar/go/1.9/libexec/src/strings/reader.go:72:1: exported method Reader.UnreadByte should have comment or be unexported
/usr/local/Cellar/go/1.9/libexec/src/strings/reader.go:81:1: exported method Reader.ReadRune should have comment or be unexported
/usr/local/Cellar/go/1.9/libexec/src/strings/reader.go:96:1: exported method Reader.UnreadRune should have comment or be unexported

Shouldn't it, at least where it won't break compat?

[dsnet]

At least two reasons:

• Much of the standard library was written before the development of "idiomatic Go", so there is still quite a bit of cruft that is written in ugly Go code.
• lint is not an infallible oracle. It's output are more like guidelines. The "exported X should have comment or be unexported" is a lint rule I personally find very annoying and usually unhelpful.

[mvdan]

I agree that the rule is often too agressive. For example, I filed https://github.com/golang/lint/issues/218 a while ago.

@willfaught if you see any warnings of it that make sense (such as inconsistent method receiver names) and want to send a patch, by all means do so. But I don't think an umbrella issue to get golint happy with std is helpful, at least right now.

[willfaught]

Much of the standard library was written before the development of "idiomatic Go", so there is still quite a bit of cruft that is written in ugly Go code.

Makes sense. Why not update it within compat limits?

lint is not an infallible oracle. It's output are more like guidelines. The "exported X should have comment or be unexported" is a lint rule I personally find very annoying and usually unhelpful.

I find it helpful. For example, in the rare case where it's pretty clear what it does, like a Write(p []byte) (n int, err error) method, it costs almost no effort to just put a // Write implements io.Writer. comment to point newbies (or those who are just tired and don't recognize it) to more information. String() string methods should document their format. Most things can benefit from at least one short line.

If go/ast and go/types followed this rule, for example, it would be much clearer how to use them. I've had to do numerous experiments to understand how they work, which should have just been documented.

[dsnet]

Makes sense. Why not update it within compat limits?

Feel free to contribute changes to clean-up crufty code.

For common interfaces, I believe it should be a tooling issue to make it clear that a type satisfies an interface and that the primary documentation should be on the interface. See #20131.

[dsnet]

Is there anything in particular that is actionable here? Otherwise, we can just close this issue. Submissions to cleanup of old code can happen whenever. Documentation changes can also happen whenever, but I personally would like to see something like #20131 happen first before blindly putting something like "MethodX implements InterfaceX" on everything.

[jimmyfrasche]

@dsnet #20131 is only going to link in the packages that contain the definition of the interface itself, not interfaces from other package. It could later be extended to cover super common interfaces like that, I suppose.

Regardless, I'm not a fan of "X is an X" boilerplate documentation.

[willfaught]

Is there anything in particular that is actionable here?

To the extent that the work that this calls for is specific, yes: make the stdlib pass golint as much as possible. Any PRs for that work could refer to this issue for justification ("Fixes #21779").

[gopherbot]

Change https://golang.org/cl/139097 mentions this issue: net/http: golint var and function name fixes

[gopherbot]

Change https://golang.org/cl/151017 mentions this issue: cmd/cgo: fix linter error for error_ function