diff options
author | Bryan C. Mills <bcmills@google.com> | 2016-07-12 18:56:07 -0400 |
---|---|---|
committer | Bryan Mills <bcmills@google.com> | 2016-07-13 16:19:07 +0000 |
commit | 2fcb25e07b2549f607aa174ceab974f8732ea0f4 (patch) | |
tree | 166b21d42315ed0ac8899f465b1eac74eb79c702 | |
parent | a1110c39301b21471c27dad0e50cdbe499587fc8 (diff) | |
download | go-2fcb25e07b2549f607aa174ceab974f8732ea0f4.tar.gz go-2fcb25e07b2549f607aa174ceab974f8732ea0f4.zip |
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>
-rw-r--r-- | doc/effective_go.html | 14 |
1 files changed, 6 insertions, 8 deletions
diff --git a/doc/effective_go.html b/doc/effective_go.html index 1e66c0c614..f6fe48c8d0 100644 --- 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> --> - |