CC @griesemer

My reading of your write-up is that one could reasonably (w/o prior Go knowledge) interpret the sentence "immediately before the surrounding function returns" as "immediately before the surrounding function executes a return statement" - would that be an accurate summary, @seebs ?

I think the crucial part here is that that first part of the sentence (which is actually written slightly differently in the spec) is followed by a clarifying 2nd part of the sentence:

... either because the surrounding function executed a return statement, reached the end of its function body, or because the corresponding goroutine is panicking.

It says pretty clearly that (for instance), the surrounding function already executed a return statement, that is the deferred function execution does happen after the return statement. But perhaps, given the subtleties involved here, this is not clear enough. There's also an example to that effect, but the associated comment is perhaps a bit too subdued.

Leaving this open for now. It's probably worthwhile being a bit more explicit.

That's a really good question. I think I would agree that this at least strongly implies that it has to be happening after the return "executed", but I could also see someone inferring that the sequence of events is:

1. control flow reaches a return statement, and begins executing it.
2. at this point, it has "executed a return statement" and defers start happening.
3. defers start happening.
4. the return actually happens.

in particular, if you haven't run into the "named return values" special syntax, it's pretty easy to think that the term probably refers to "the values given to the return statement, if they are named objects that the deferred function literals could modify".

I did a writeup explaining this (which i eventually plan to do a thing with other than stash it in a repo somewhere) for the benefit of new users:

https://github.com/seebs/notes/blob/master/defer_return.md

The key thing missing, i think, is the distinction between "the return causes the return values to become set" and "the return causes control flow to transfer back to the caller". If you think of those as a single "return" operation, than defer basically has to happen before the return statement changes the values-that-will-be-returned. (Note, "missing" in the mental model people might have when coming to this, I think the spec basically communicates this, it's just easy to have a mental model which makes it plausibly seem to say something else.)

@seebs Thanks for the clarification; I agree with the key thing that's missing (per the mental model you are referring to). I think this shouldn't be too hard to make crystal clear in the spec.

Thanks!

Amusingly, the genesis of this is that someone was being confused by this, and I was going to try to write an explanation of why the spec's adequately clear and he just wasn't reading carefully enough, and then after a couple of tries at this I realized that the spec's wording was making it unduly difficult to express the thing without apparently contradicting the spec, or at least requiring a large digression into why what I was saying didn't contradict it.

Change https://golang.org/cl/136758 mentions this issue: spec: be more precise about moment deferred functions are executed