What is the idiomatic way to return either a struct or an error?

I have a function that returns either a Card, which is a struct type, or an error.

The problem is, how can I return from the function when an error occurs ? nil is not valid for structs and I don't have a valid zero value for my Card type.

func canFail() (card Card, err error) {
    // return nil, errors.New("Not yet implemented"); // Fails
    return Card{Ace, Spades}, errors.New("not yet implemented"); // Works, but very ugly
}

The only workaround I found is to use a *Card rather than a Card, a make it either nil when there is an error or make it point an actual Card when no error happens, but that's quite clumsy.

func canFail() (card *Card, err error) {
    return nil, errors.New("not yet implemented");
}

Is there a better way ?

EDIT : I found another way, but don't know if this is idiomatic or even good style.

func canFail() (card Card, err error) {
    return card, errors.New("not yet implemented")
}

Since card is a named return value, I can use it without initializing it. It is zeroed in its own way, I don't really care since the calling function is not supposed to use this value.

func canFail() (card Card, err error) {
    return card, errors.New("not yet implemented")
}

I think this, your third exampe, is fine too. The understood rule is that when a function returns an error, other return values cannot be relied upon to have meaningful values unless documentation clearly explains otherwise. So returning a perhaps meaningless struct value here is fine.

For example,

type Card struct {
}

func canFail() (card Card, err error) {
	return Card{}, errors.New("not yet implemented")
}

func canFail() (card Card, err error) {
        if somethingWrong {
                err = errors.New("Not yet implemented")
                return
        }

        if foo {
                card = baz
                return
        }

        ... 

        // or 
        return Card{Ace, Spades}, nil
}

For me, I prefer your second option.

func canFail() (card *Card, err error) {
    return nil, errors.New("not yet implemented");
}

This way you can make sure that when errors happen, the canFail() callers won't be able to use the card since it's nil. We can't make sure that the callers will check the error first.

peterSO's answer is the closest, but it's not quite what I would use. I think this is best:

func canFail() (Card, error) {
   return Card{}, errors.New("not yet implemented")
}

First, it's not using a pointer just so it can use nil for returns. I think that's a neat trick, but unless you actually need the struct to be a pointer (for modifying or other reason), then returning a value is better. Also I don't think the return values should be named, unless you are utilizing them, like this:

func canFail() (card Card, err error) {
   return
}

and that is problematic for two reasons. First, you aren't always going to be in a situation where you can simply have the return value be whatever that variable is at the time. Second, if you have a larger function, you won't be able to use a naked return in the deeper levels, as you will get variable shadow errors.

Finally, using Card{} instead of nil or card is more verbose, but it better communicates what you are doing. If you use either of these:

return
return card, err

It's not clear without context if the function was successful or not, while this:

return Card{}, err

is pretty clear that the function failed. It's the same pattern you would use with primitive types:

return false, err
return 0, err
return '\x00', err
return "", err
return []byte{}, err

https://github.com/golang/go/wiki/CodeReviewComments#pass-values

As a possible alternative to returning the struct you might consider letting the caller allocate it and the function set params.

func canFail(card *Card) (err error) {
	if someCondition {
		// set one property
		card.Suit = Diamond

		// set all at once
		*card = Card{Ace, Spade}
	} else {
		err = errors.New("something went wrong")
	}

	return
}

If you are not comfortable pretending that Go supports C++ style references you should also check card for being nil.

https://play.golang.org/p/o-2TYwWCTL

If your function does not behave like someone else would assume reading at its signature, IE, if an error has occurred I should ignore the value along it.

Pretty much like any io.Reader, which may return n>0 with an error

Then, you should simply document it to explain to the user what should be considered regarding the returned value along the error.

Changing the signature, thus the general API relationships, for such case, rare but not unavoidable, is not the way to Go.

Instead, you should adequatly document the behavior of the function.