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>
This commit is contained in:
Bryan C. Mills 2016-07-12 18:56:07 -04:00 committed by Bryan Mills
parent a1110c3930
commit 2fcb25e07b
1 changed files with 6 additions and 8 deletions

View File

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