mirror of https://github.com/golang/go.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 <r@golang.org> Reviewed-by: Andrew Gerrand <adg@golang.org>
This commit is contained in:
parent
a1110c3930
commit
2fcb25e07b
|
|
@ -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>
|
||||
-->
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue