From 2fcb25e07b2549f607aa174ceab974f8732ea0f4 Mon Sep 17 00:00:00 2001 From: "Bryan C. Mills" Date: Tue, 12 Jul 2016 18:56:07 -0400 Subject: [PATCH] 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 --- doc/effective_go.html | 14 ++++++-------- 1 file 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 {

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