Go subtleties

The advice I've read (and follow) is always to return values, not interfaces, from functions and test for nil against them. That IME tends to nip the majority of nil interface problems in the bud.

Exactly.

I find that people try to use interfaces like they’re using an OO language. Go is not OO.

Return concrete types, accept interfaces. Returning interfaces hides behavior and hampers evolution; accept interfaces so callers can swap implementations. For testing, mock the dependency, not the return value.

Loudest arguments against returning concrete types were on the terraform core team and the excuse was it makes testing easier. I disagree.

This advice of "returning concrete types" is in most cases a horrible anti-pattern that prevents evolution due to lack of information hiding. It has been also deliberately broken in the standard library in several places. This "advice" cannot be generically applied. Places where it is has been deliberately broken:

   net.Dial (Conn, error) 
   image.Decode(r io.Reader) (Image, string, error)
   sha256.NewXXX() hash.Hash
   flate.NewReader(r io.Reader) io.ReadCloser
   http.NewFileTransport(fs FileSystem) RoundTripper

Regarding `os.File`, the Go team even said: “If we were starting from scratch, we might do it differently.”

That’s why Go added abstractions later like fs.FS and fs.File.

   embed/fs.Open again deliberately breaks this.

Whereas consider its counterpart net.Conn. net.Conn is one of the most successful interfaces in the Go standard library. It’s the foundation of the net, net/http, tls, and net/rpc packages, and has been stable since Go 1.0. It didn't need a replacement fs.Fs.

If you will always only ever have one implementation in absolute permanence and no mocking/fake/alternative implementation is ever required in eternity, return a concrete type. Otherwise, consider whether returning an interface makes more sense.

That works until 1) you don't want to export the value types 2) the return values aren't simple structs but slices or maps because []x is not a []X even if x implements X.

On the contrary, in recent proposal reviews, returning interfaces has been discouraged unless you're trying to make a generic interface like fs.FS, or dispatch functions like net.Dial / image.Decoder.

The advice of returning concrete types is paired with defining interfaces when you need them on the consumer side.

It's returning interfaces that prevents good evolution, since the standard library will not add methods to interfaces, it can only document things like: all current standard library implementations additionally satisfy XXX interfaces.

> the return values aren't simple structs but slices or maps because []x is not a []X even if x implements X.

I assume this is because on is an array of struct pointers and the other is an array of fat pointers, since Go has reified interfaces (unlike higher-level languages).

For 1/, you can return a struct value type without exporting it. If it satisfies the receiving interface they won’t have a problem.

That’s exactly the pattern I use for most Go development

On the happy path downstream, yes, and it does work really well. But the error flow back upstream flips that, as errors are returned as, often nested, interfaces.

This is fine for a lot of general purpose code that exits when running into problems. But when errors are an expected part of a long lived process, like an API, it’s painful to build logic around and conditionally handle them.

The ergonomics of errors.Is and As are pretty bad and there doesn’t seem to be a clear indication as when to expect a sentinel, concrete, or pointer to a concrete error.

All that to say, I think Go’s errors really illustrate the benefit of “return values, not interfaces”. Though for errors specifically, I’m not sure you could improve them without some pretty bad tradeoffs around flexibility.

It seems there is a dichotomy in the real implemented world and your hypothetical advice world.

Due to lack of native support of defaults for optional methods , many interfaces in Go are using hacks for optional methods added by evolution.

The Value interface has a `IsBoolFlag()` optional method not part of the interface signature

The other way for evolution is just add sub-interfaces. Like `io.WriterTo` and `io.ReaderFrom` which are effectively just extensions of `io.Writer` and `io.Reader` with `WriteTo` and `ReadFrom` methods - which are checked for in consumers like `io.Copy`.

Anyways, my point was specifically about generic interfaces and alternative implementations, so it appears you agree.

Like anything else there are exceptions to the rule. Pointing to the standard library is a weak position because it is consistently inconsistent.

Go's standard library interfaces (like net.Conn) earned their place.

Premature interfaces calcify mistakes and that's what the guideline pushes back on.

This affects discoverability, though. Your unexported type won't have public documentation. So you end up having to publish an interface anyway (even if you don't return it) or document in words what the method set looks like.