From: Bryan C. Mills Date: Tue, 12 Jul 2016 22:56:07 +0000 (-0400) Subject: doc/effective_go: clarify advice on returning interfaces X-Git-Tag: go1.7rc3~1^2~22 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=2fcb25e07b2549f607aa174ceab974f8732ea0f4;p=gostls13.git 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 Reviewed-by: Andrew Gerrand --- 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 {

Generality

-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.

@@ -3665,4 +3664,3 @@ var _ image.Color = Black var _ image.Image = Black --> -