STYLE: Clarify when to use pointer or value receivers

Our current policy with regards to pointer vs. value receivers is not
documented anywhere. Given that we have a policy saying that if a single
method requires a pointer receiver, all methods should be pointer
receivers, there's some non-obvious bits to our coding style. So let's
write this part down so we can point to it from now on.

1 files changed, 8 insertions, 1 deletions

diff --git a/STYLE.md b/STYLE.md
index c82061123..c4b31667b 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -144,7 +144,14 @@ digits, but then you may not use a `4` as the first digit. 0377 equals
 hexadecimal you cannot make this mistake because the largest two digit
 hex number is 0xff which equals 255.
 
-## Return statements
+## Functions
+
+### Method Receivers
+
+Without any good reason, methods should always use value receivers, where good
+reasons include (but are not limited to) performance/memory concerns or
+modification of state in the receiver. Otherwise, if any of the type's methods
+requires a pointer receiver, all methods should be pointer receivers.
 
 ### Don't use "naked return"