In Go, what is the difference between a value receiver and a pointer receiver on a method?

## The receiver is a parameter A Go method is an ordinary function with one extra parameter written in front of the name: ```go func (o Order) Total() int64 // receiver type Order — a value receiver func (o *Order) Add(minor int64) // receiver type *Order — a pointer receiver ``` Go has exactly one argument-passing rule: everything is passed by value, a copy. The receiver is no exception. What differs between the two forms is *what* gets copied. - **Value receiver `Order`** — the whole struct is copied into the method. The body's `o` is a separate `Order` that happens to start out equal to the caller's. Fields written inside the method are written on that copy, and the copy is thrown away when the method returns. - **Pointer receiver `*Order`** — the *pointer* is copied (a machine word). Both the caller's variable and the method's `o` refer to the same `Order`, so `o.TotalMinor += minor` mutates the one the caller holds. ## The failure this causes The compiler is perfectly happy with a value-receiver method that assigns to its receiver's fields — writing to a local copy is legal code. Nothing warns you. So a checkout state machine written like this compiles, runs, and silently does nothing: ```go type Order struct { Status string TotalMinor int64 // amount in minor units, e.g. cents } func (o Order) ApplyFee(minor int64) { o.TotalMinor += minor // written to the copy, lost at return } ``` Call `order.ApplyFee(250)` and `order.TotalMinor` is unchanged. Change the receiver to `*Order` and the same body works. This is the single most common first-week Go bug for engineers arriving from a language where an object variable is already a reference; there, calling a mutating method on an object just works, and the copy is invisible until you look for it. ## How to choose The practical checklist: 1. **Does the method modify the receiver?** Then it must be a pointer receiver. There is no other option short of returning a new value. 2. **Does the type carry state that must not be duplicated** — a lock, a counter shared with other goroutines, a handle to something that gets closed? Then pointer receivers, so nobody accidentally works on a second copy of that state. 3. **Is the type large?** A value receiver copies every field on every call. For a struct of a few words this is free and may even be faster than chasing a pointer; for a fat struct in a hot loop it is real work. 4. **Is the type small and conceptually a value** — an amount in minor units, a coordinate, a duration-like number? Value receivers read well and let callers treat it like any other number. 5. **Consistency wins ties.** Go's convention is that a type uses one receiver form throughout. If any method needs a pointer, give them all pointers, so the reader of a call site never has to check the declaration to know whether the call mutates. ## Things that are true but often misstated - A value receiver does **not** give you deep immutability. It stops the method from changing the caller's copy of the fields; it does not stop it from writing through any pointer, slice or map the struct contains. - A pointer receiver is **not** automatically faster. It avoids the struct copy but adds an indirection, and it can push the value onto the heap. - A pointer receiver does **not** make the method safe for concurrent use. Sharing one value between goroutines is precisely what makes synchronisation necessary. - The alternative to mutation is to return the new value: `func (o Order) WithFee(minor int64) Order`. That keeps the value semantics and makes the update visible at the call site as an assignment. ## The mental model to keep Read `func (o Order) M()` as `func M(o Order)` and `func (o *Order) M()` as `func M(o *Order)`. Every question about what a method can and cannot change answers itself once the receiver is back in the parameter list where it belongs.