code review 4852041: FAQ: lots of small tweaks plus a couple of new discussions.

FAQ: lots of small tweaks plus a couple of new discussions.
Expand the conversations about pointers, memory, and
garbage collection.
Describe the lack of co/contravariant typing.

Fixes issue 1929.
Fixes issue 1930.

[r, 2011-08-05 04:54:32]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://go.googlecode.com/hg/

[dsymonds, 2011-08-05 05:08:22]

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html
File doc/go_faq.html (left):

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#oldcode29
doc/go_faq.html:29: </p>
why remove these?

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode319
doc/go_faq.html:319: <a
href="http://blog.golang.org/2011/07/error-handling-and-go.html">coupled
I'd link the whole start of the sentence ("A canonical error type, coupled with
Go's other features").

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode321
doc/go_faq.html:321: handling pleasant but quite different from that in most
C-like languages.
s/C-like/other/

C-like is true, but I think it's a distraction here.

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode624
doc/go_faq.html:624: with Go's types <code>T1</code> does <em>not</em> implement
<code>Equaler</code>.
s/with Go's types/Go's type/

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode644
doc/go_faq.html:644: We feel this simplicity offsets the lack of
maybe mention that it's a lot more efficient too? That's a significant factor in
this trade-off.

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode816
doc/go_faq.html:816: If it does, the receiver <em>must</em> be a pointer. In the
examples
that's not true for reference types.

[r, 2011-08-05 05:19:09]

Hello golang-dev@googlegroups.com, dsymonds@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[dsymonds, 2011-08-05 05:21:40]

LGTM

http://codereview.appspot.com/4852041/diff/4001/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/4001/doc/go_faq.html#newcode321
doc/go_faq.html:321: canonical error type,coupled
space after comma

http://codereview.appspot.com/4852041/diff/4001/doc/go_faq.html#newcode626
doc/go_faq.html:626: with Go type <code>T1</code> does <em>not</em> implement
<code>Equaler</code>.
the "with" doesn't belong here now.
("Go type T1" is now the subject phrase)

[r, 2011-08-05 05:23:35]

Hello golang-dev@googlegroups.com, dsymonds@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r2, 2011-08-05 05:23:52]

waiting for any others who want to weigh in

[aam, 2011-08-05 05:27:31]

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode1363
doc/go_faq.html:1363: Go programs</a> for a worked example, including a
demonstration of Go's
did you mean 'working' here? if you didn't, then the wording is confusing to a
non-native reader.

[r2, 2011-08-05 05:28:35]

On Aug 5, 2011, at 3:27 PM, mirtchovski@gmail.com wrote:

> 
> http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html
> File doc/go_faq.html (right):
> 
> http://codereview.appspot.com/4852041/diff/1/doc/go_faq.html#newcode1363
> doc/go_faq.html:1363: Go programs</a> for a worked example, including a
> demonstration of Go's
> did you mean 'working' here? if you didn't, then the wording is
> confusing to a non-native reader.

i did mean 'worked', but point taken.

-rob

[eds2, 2011-08-05 05:58:54]

I was promised a paragraph about compiler errors vs. warnings a while
back. It doesn't have to be in this CL, but just a reminder.

- Evan

[r2, 2011-08-05 06:08:50]

there is more to come

[hanwen-google, 2011-08-05 14:30:09]

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode602
doc/go_faq.html:602: Are types in Go covariant/contravariant?</h3>
I had to look up what this means since I never heard anyone use these terms. 
Maybe you could use simpler terminology? ("Does Go have implicit type
conversions?")

[kevlar, 2011-08-05 17:12:17]

FYI

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode643
doc/go_faq.html:643: While it is true that Go's type system does less for the
programmer in such cases, the lack of subtype
I can't tell from the rest of this document if it's supposed to be 80col or not,
but a few lines in this block of green are a few characters past it.

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode831
doc/go_faq.html:831: </p>
You mention reference types in here as being a somewhat "special case".  In my
mind, they're not special, their values just happen to refer to data that is not
copied along with them, just like a struct with a pointer member that is passed
by value.  I don't have any good ideas about how to express this in a FAQ entry,
though, but I thought I'd mention it in case you do.

[rsc, 2011-08-05 21:03:55]

Looks good except for the *variant types.

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode602
doc/go_faq.html:602: Are types in Go covariant/contravariant?</h3>
I agree but I don't know how to rewrite the heading.

If T implements Reader, why can't I use a func() T as a func() Reader?

something like that.

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode609
doc/go_faq.html:609: <pre>
This is not an example of contravariance/covariance,
at least not directly.

type Equaler interface {
    Equal(Equaler) bool
}

func (t T1) Equal(u T1) bool

In this example the problem is that an Equaler's Equal method
must accept *any* Equaler, while Equal accepts only T1.
Even a language like ML wouldn't accept this.

You might be able to reuse this example to answer
"Does Go have parametrized types?" but the answer for
why it doesn't work is that the receiver and the argument
might be *different* types implementing Equaler, and
in particular the argument might not be a T1 even if the
receiver were a T1.  And then on top of that, there's no
covariance.  So it's probably too technical.

An example for the question in the headline would be:

type Opener interface {
    Open(name) Reader
}

func (t T) Open() *os.File

T does not implement Opener even though it might in a
less strict language.

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode802
doc/go_faq.html:802: func (s  MyStruct) valueMethod()   { } // method on value
Either way but the old spacing had the advantage of
making the two lines more obviously different.

http://codereview.appspot.com/4852041/diff/6002/doc/go_faq.html#newcode841
doc/go_faq.html:841: the semantics of the method requires a pointer, a value
receiver is efficient and clear.
It is not required that the methods for a particular type all have pointer
receivers or all have value receivers, but it is typical to be consistent across
methods.

terrible wording but you get the point

[r, 2011-08-05 21:31:43]

Hello dsymonds@golang.org, r@google.com, mirtchovski@gmail.com,
edsrzf@gmail.com, hanwen@google.com, rsc@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[hanwen-google, 2011-08-05 21:33:46]

LGTM 

(the (contra)variant stuff.)

[rsc, 2011-08-05 21:35:34]

LGTM

http://codereview.appspot.com/4852041/diff/12001/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4852041/diff/12001/doc/go_faq.html#newcode625
doc/go_faq.html:625: Unlike the analogous situation in some object-oriented type
systems,
s/the/an/
s/object-oriented/polymorphic/

http://codereview.appspot.com/4852041/diff/12001/doc/go_faq.html#newcode670
doc/go_faq.html:670: in such cases, the lack of subtype inheritance makes the
rules about
s/subtype inheritance/subtyping/

[r, 2011-08-05 21:42:10]

*** Submitted as http://code.google.com/p/go/source/detail?r=f518f530b2d2 ***

FAQ: lots of small tweaks plus a couple of new discussions.
Expand the conversations about pointers, memory, and
garbage collection.
Describe the lack of co/contravariant typing.

Fixes issue 1929.
Fixes issue 1930.

R=dsymonds, r, mirtchovski, edsrzf, hanwen, rsc
CC=golang-dev
http://codereview.appspot.com/4852041