doc/effective_go: clarify advice on returning interfaces

New Gophers sometimes misconstrue the advice in the "Generality" section
as "export interfaces instead of implementations" and add needless
interfaces to their code as a result.  Down the road, they end up
needing to add methods and either break existing callers or have to
resort to unpleasant hacks (e.g. using "magic method" type-switches).

Weaken the first paragraph of this section to only advise leaving types
unexported when they will never need additional methods.

Change-Id: I32a1ae44012b5896faf167c02e192398a4dfc0b8
Reviewed-on: https://go-review.googlesource.com/24892
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/doc/effective_go.html b/doc/effective_go.html
index 1e66c0c6145faee0cf5a0dfd86c0e21b9a556b03..f6fe48c8d0465b4892b6c38863825e4976177270 100644 (file)
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -2238,13 +2238,12 @@ if str, ok := value.(string); ok {
 
 <h3 id="generality">Generality</h3>
 <p>
-If a type exists only to implement an interface
-and has no exported methods beyond that interface,
-there is no need to export the type itself.
-Exporting just the interface makes it clear that
-it's the behavior that matters, not the implementation,
-and that other implementations with different properties
-can mirror the behavior of the original type.
+If a type exists only to implement an interface and will
+never have exported methods beyond that interface, there is
+no need to export the type itself.
+Exporting just the interface makes it clear the value has no
+interesting behavior beyond what is described in the
+interface.
 It also avoids the need to repeat the documentation
 on every instance of a common method.
 </p>
@@ -3665,4 +3664,3 @@ var _ image.Color = Black
 var _ image.Image = Black
 </pre>
 -->
-