Why would return parameters be named?

What benefits arise from naming a function's return parameter(s)?

func namedReturn(i int) (ret int) {
    ret = i
    i += 2
    return
}

func anonReturn(i int) int {
    ret := i
    i += 2
    return ret
}

There are some benefits to naming them:

• It serves as documentation.
• They are auto-declared and initialized to the zero values.
• If you have multiple return sites, you don't need to change them all if you change the function's return values since it will just say "return".

There are also downsides, mainly that it's easy to accidentally shadow them by declaring a variable of the same name.

<br/>

Effective Go has a section on named result parameters:

> The return or result "parameters" of a Go function can be given names
> and used as regular variables, just like the incoming parameters. When
> named, they are initialized to the zero values for their types when
> the function begins; if the function executes a return statement with
> no arguments, the current values of the result parameters are used as
> the returned values.
>
> The names are not mandatory but they can make code shorter and
> clearer: they're documentation. If we name the results of nextInt it
> becomes obvious which returned int is which.
>
> func nextInt(b []byte, pos int) (value, nextPos int) {
> [...]

Another special use for a named return variable is to be captured by a deferred function literal. A trivial illustration:

package main

import (
	"errors"
	"fmt"
)

func main() {
	fmt.Println(f())
}

var harmlessError = errors.New("you should worry!")

func f() (err error) {
	defer func() {
		if err == harmlessError {
			err = nil
		}
	}()
	return harmlessError
}

Output is <nil>. In more practical scenarios, the deferred function may handle panics, and may modify other return values besides an error result. The magic in common though, is that the deferred literal has a chance to modify the return values of f after f is terminated, either normally or by panic.

It's useful in at least two cases:

1. Whenever you have to declare variables that you're going to return. E.g.

    func someFunc() (int, error) {
        var r int
        var e error
        ok := someOtherFunc(&r)  // contrived, I admit
        if !ok {
            return r, someError()
        }
        return r, nil
    }
   

   vs.

    func someFunc() (r int, e error) {
        ok := someOtherFunc(&r)
        if !ok {
            e = someError()
        }
        return
    }
   

   This gets more important as the number of execution paths through the function increases.

2. When you're documenting return values and want to refer to them by name. godoc considers the return variables part of a function's signature.

For example, named return parameters are accessible by, well, name.

func foo() (a, b, c T) {
        // ...
        if qux {
                b = bar()
        }
        // ...
        return
}

This is not easy to replicate w/o named return parameters. One would have to introduce local variables of essentially the same functionality as named return parameters:

func foo() (T, T, T) {
        var a, b, c T
        // ...
        if qux {
                b = bar()
        }
        // ...
        return a, b, c
}

So it's easier to allow that directly.

Additionally, they are accessible also in the other direction:

func foo() (a, b, c T) {
        // ...
        if a > c {
                b = bar()
        }
        // ...
        return
}

Etc.