When should I define methods on values (instead of on pointers) in Go?

Question

Having defined

type MyInt int

I would like to define a method .ShowMe() that just prints the value. I can define this either using *MyInt:

func (this *MyInt) ShowMe() {
    fmt.Print(*this, "\n")
}

Or using MyInt:

func (this MyInt) ShowMe() {
    fmt.Print(this, "\n")
}

In what cases is it recommended to define methods on values, instead of on pointers?

Answer 1

The Go FAQ (CC-licensed) has an answer:

Should I define methods on values or pointers?

func (s *MyStruct) pointerMethod() { } // method on pointer
func (s MyStruct)  valueMethod()   { } // method on value

For programmers unaccustomed to pointers, the distinction between these two examples can be confusing, but the situation is actually very simple. When defining a method on a type, the receiver (s in the above example) behaves exactly as if it were an argument to the method. Whether to define the receiver as a value or as a pointer is the same question, then, as whether a function argument should be a value or a pointer. There are several considerations.

First, and most important, does the method need to modify the receiver? If it does, the receiver must be a pointer. (Slices and maps are reference types, so their story is a little more subtle, but for instance to change the length of a slice in a method the receiver must still be a pointer.) In the examples above, if pointerMethod modifies the fields of s, the caller will see those changes, but valueMethod is called with a copy of the caller's argument (that's the definition of passing a value), so changes it makes will be invisible to the caller.

By the way, pointer receivers are identical to the situation in Java, although in Java the pointers are hidden under the covers; it's Go's value receivers that are unusual.

Second is the consideration of efficiency. If the receiver is large, a big struct for instance, it will be much cheaper to use a pointer receiver.

Next is consistency. If some of the methods of the type must have pointer receivers, the rest should too, so the method set is consistent regardless of how the type is used. See the section on method sets for details.

For types such as basic types, slices, and small structs, a value receiver is very cheap so unless the semantics of the method requires a pointer, a value receiver is efficient and clear.

Answer 2

There are two questions to ask yourself when making this decision:

1. Do I want to be able to modify the receiver's value?
2. Will copying the receiver's value be expensive?

If the answer to either of these questions is yes, then define the method on a pointer.

In your example, you don't need to modify the receiver's value and copying the receiver isn't expensive.

For deciding the answer to #2, my rule of thumb is: if the receiver is a struct with more than one field, pass by pointer. Otherwise pass by value.