code review 218070: First run at a Programming FAQ

First run at a Programming FAQ

Moved a couple of FAQs from the main FAQ, and added some others

[adg, 2010-02-23 18:34:33]

Hello r, rsc (cc: golang-dev@googlegroups.com),

I'd like you to review this change.

[iant, 2010-02-23 18:53:51]

FYI

http://codereview.appspot.com/218070/diff/5/6
File doc/go_faq.html (right):

http://codereview.appspot.com/218070/diff/5/6#newcode87
doc/go_faq.html:87: programs. The Go team is small and we don't have the
resources to do a
I would drop "The Go team" sentence and bring the next paragraph into this one,
dropping the initial "However".

http://codereview.appspot.com/218070/diff/5/6#newcode93
doc/go_faq.html:93: <a href="http://www.mingw.org/">MinGW</a> by a group of
enthusiasts.
s/enthusiasts/volunteers/

http://codereview.appspot.com/218070/diff/5/7
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/5/7#newcode119
doc/go_programming_faq.html:119: </p>
Perhaps add a new paragraph:

The size of int on 64-bit systems is consistent with the behaviour of most C/C++
compilers: generally int is 32-bits for C/C++.  Go does not have to be
consistent with C/C++, but it doesn't hurt.

[adg, 2010-02-23 18:56:53]

Hello r, rsc, iant (cc: golang-dev@googlegroups.com),

Please take another look.

[rsc, 2010-02-23 19:21:42]

looks like a good start.

might also close issue 232.

http://codereview.appspot.com/218070/diff/11/12
File doc/go_faq.html (right):

http://codereview.appspot.com/218070/diff/11/12#newcode87
doc/go_faq.html:87: programs.  Significant progress is being made toward porting
Go to
Avoid passive voice.

A group of volunteers has made significant progress toward porting Go to Windows
using MinGW.  You can follow ...

http://codereview.appspot.com/218070/diff/11/13
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/11/13#newcode39
doc/go_programming_faq.html:39: When should I pass by value, and when should I
pass a pointer?</h3>
Passing a pointer is still passing by value.
I'd suggest making the question

When are function parameters passed by value?

and then drop the "One way of thinking about it:" prefix.

http://codereview.appspot.com/218070/diff/11/13#newcode104
doc/go_programming_faq.html:104: See the <a
href="/doc/effective_go.html#allocation_new">relevant section
can drop "the relevant section of"

s/for a thorough .*/for more details/

whether it's thorough is up to the reader.  ;-)

http://codereview.appspot.com/218070/diff/11/13#newcode110
doc/go_programming_faq.html:110: Why is int an int32 on under 6g?</h3>
nit: int is not an int32.

Why is int 32 bits on 64-bit machines?

http://codereview.appspot.com/218070/diff/11/13#newcode114
doc/go_programming_faq.html:114: Presently, the 64-bit Go compiler uses an
the 64-bit Go compilers (both 6g and gccgo) use a 32-bit representation for both
int and float.
Code that relies on a particular size of value should use an
explicitly sized type, like int64 or float64.

http://codereview.appspot.com/218070/diff/11/13#newcode136
doc/go_programming_faq.html:136: <a href="go_lang_faq.html">language design
FAQ</a>.
inconsistent about whether there is </p> after parargraph

http://codereview.appspot.com/218070/diff/11/13#newcode150
doc/go_programming_faq.html:150: Why does setting GOMAXPROCS >1 make my program
slower?</h3>
I'd rather start with

Why doesn't my multi-goroutine program use multiple CPUs?

and then add

Why does using GOMAXPROCS > 1 sometimes slow down my program?

http://codereview.appspot.com/218070/diff/11/13#newcode209
doc/go_programming_faq.html:209: // *not* the value of v when the goroutine was
created
put actual code here too
fmt.Println(v)

same in next one

[gri, 2010-02-23 19:24:20]

FYI.

http://codereview.appspot.com/218070/diff/11/13
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/11/13#newcode10
doc/go_programming_faq.html:10: Source files can refer to items from different
files at will; there is
With the exception of imports. For instance, if one file imports "math", one
cannot refer for math.Sin from another file. It must  import "math" itself. Not
sure this is the place to emphasize this, but it could come up.

http://codereview.appspot.com/218070/diff/11/13#newcode59
doc/go_programming_faq.html:59: value holds a struct, the copying the interface
value makes a copy of the
s/the copying/copying/

[adg, 2010-02-23 20:04:14]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[r, 2010-02-23 21:16:44]

lots of comments but this is a great start

http://codereview.appspot.com/218070/diff/19/21
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/19/21#newcode5
doc/go_programming_faq.html:5: <h3 id="How_do_I_create_a_multifile_package">
this is a strange choice for first question. this and the next should be towards
the bottom since they address high-level issues that arise once you've used the
language some

http://codereview.appspot.com/218070/diff/19/21#newcode43
doc/go_programming_faq.html:43: When are function paramters passed by
value?</h3>
much of this question defines pointers. maybe it's important to do so but this
is c.s. 101. can you say it's like C or C++ or java for that matter, with a
paragraph about maps and slices?

at least shorten it.

http://codereview.appspot.com/218070/diff/19/21#newcode56
doc/go_programming_faq.html:56: copy a file, and copying a pointer doesn't copy
the data it points at (if any).
drop the parenthetical

http://codereview.appspot.com/218070/diff/19/21#newcode69
doc/go_programming_faq.html:69: Put a different way, nothing in Go is "passed by
reference".  But there are
second line is not a sentence.

http://codereview.appspot.com/218070/diff/19/21#newcode85
doc/go_programming_faq.html:85: When dealing with structs, you normally want to
define the method on a pointer
s/normally/usually/

http://codereview.appspot.com/218070/diff/19/21#newcode87
doc/go_programming_faq.html:87: useful when defining methods on types which are
not structs.
s/which/that/

you answer the question but don't explain why. why is it most useful?

there are two issues: performance and semantics. both need to be explained.

http://codereview.appspot.com/218070/diff/19/21#newcode94
doc/go_programming_faq.html:94: rather than a pointer to the struct value.  This
is not the common case, and
why is this in parens?

also, this issue gets half the copy of the previous one and probably needs twice
as much.

http://codereview.appspot.com/218070/diff/19/21#newcode113
doc/go_programming_faq.html:113: Why is int an 32-bits on 64-bit machines?</h3>
int should be <code>


'an 32-bits' ? why 'an'? why the hyphen?

http://codereview.appspot.com/218070/diff/19/21#newcode117
doc/go_programming_faq.html:117: Presently, the 64-bit Go compilers (both 6g and
gccgo) use a 32-bit
Presently is a meaningless word because the sentence is in the present tense.
drop it.

http://codereview.appspot.com/218070/diff/19/21#newcode125
doc/go_programming_faq.html:125: C/C++ compilers: generally int is 32-bits for
C/C++.  Go does not have to be
use <code> when using words like int

http://codereview.appspot.com/218070/diff/19/21#newcode157
doc/go_programming_faq.html:157: from an increase in <code>GOMAXPROCS</code>.
only true for 6g, not gccgo

http://codereview.appspot.com/218070/diff/19/21#newcode164
doc/go_programming_faq.html:164: It is largely dependant on the nature of your
program.
the adjective is spelled 'dependent'.

drop the adverb too

It depends on the nature of your program.

http://codereview.appspot.com/218070/diff/19/21#newcode165
doc/go_programming_faq.html:165: Programs that consists of several goroutines
that spend a lot of time
number error.  fix by s/consists of/contain/

http://codereview.appspot.com/218070/diff/19/21#newcode168
doc/go_programming_faq.html:168: penalty involved in sending data between
threads.
well, yes and no.  the real issue is whether the program is parallelizable at
all. if it's not, things will slow down when written this way.  a tricky
question you haven't answered well.

http://codereview.appspot.com/218070/diff/19/21#newcode172
doc/go_programming_faq.html:172: Presently the Go runtime's scheduler is not as
good as it needs to be. In
presently again

http://codereview.appspot.com/218070/diff/19/21#newcode174
doc/go_programming_faq.html:174: now, <code>GOMAXPROCS</code> should be set on a
per-application basis.
mention you can do this programmatically if it's important to use all the cpus

in any case it should be reported that there is a function in runtime

http://codereview.appspot.com/218070/diff/19/21#newcode207
doc/go_programming_faq.html:207: You might expect to see "a, b, c" as the
output. When what you'll probably see
use <code> not quotes

second line not sentence

the question contains 'strangely'.  that's editorializing; the behavior is not
strange. rephrase or explain that it's not strange but standard.

http://codereview.appspot.com/218070/diff/19/21#newcode237
doc/go_programming_faq.html:237: (ie, the form <code>var n = expr ? trueVal :
falseVal</code> present in some
no latinisms please.  anyway it should have periods. anyway you don't need this
if you write the question better.  Does Go have the ?: operator?

[adg, 2010-02-23 22:04:21]

On 23 February 2010 13:16,  <r@golang.org> wrote:
> http://codereview.appspot.com/218070/diff/19/21#newcode87
> doc/go_programming_faq.html:87: useful when defining methods on types
> which are not structs.
> s/which/that/
>
> you answer the question but don't explain why. why is it most useful?
>
> there are two issues: performance and semantics. both need to be
> explained.

I understand the performance issues; that it is cheaper (and more
likely to be a cache hit?) to push the value onto the call stack than
to reference via a pointer. I'm not sure specifically what you mean by
semantic issues. That it's nicer not to have dereference the pointer
in the method body?

[adg, 2010-02-23 22:13:53]

On 23 February 2010 13:16,  <r@golang.org> wrote:
> http://codereview.appspot.com/218070/diff/19/21#newcode168
> doc/go_programming_faq.html:168: penalty involved in sending data
> between threads.
> well, yes and no.  the real issue is whether the program is
> parallelizable at all. if it's not, things will slow down when written
> this way.  a tricky question you haven't answered well.

Granted. I'd be grateful if someone closer to the runtime could
elaborate on this point. (Russ? Ian?)

[adg, 2010-02-23 22:46:16]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[adg, 2010-02-23 22:54:01]

There are some parts of this (eg "causing semantic ugliness") that are
placeholders. Just thought it better to keep iterating.

On 23 February 2010 14:46,  <adg@golang.org> wrote:
> Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),
>
> Please take another look.
>
>
> http://codereview.appspot.com/218070/show
>

[r2, 2010-02-23 22:57:29]

On Feb 24, 2010, at 9:03 AM, Andrew Gerrand wrote:

> On 23 February 2010 13:16,  <r@golang.org> wrote:
>> http://codereview.appspot.com/218070/diff/19/21#newcode87
>> doc/go_programming_faq.html:87: useful when defining methods on types
>> which are not structs.
>> s/which/that/
>>
>> you answer the question but don't explain why. why is it most useful?
>>
>> there are two issues: performance and semantics. both need to be
>> explained.
>
> I understand the performance issues; that it is cheaper (and more
> likely to be a cache hit?) to push the value onto the call stack than
> to reference via a pointer. I'm not sure specifically what you mean by
> semantic issues. That it's nicer not to have dereference the pointer
> in the method body?

If the method needs to modify the contents, the receiver must be  
pointer.  If not, it doesn't.

-rob

[r, 2010-02-24 03:27:19]

http://codereview.appspot.com/218070/diff/29/31
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/29/31#newcode161
doc/go_programming_faq.html:161: what you'll probably see instead is <code>c, c,
c</code>.  This is because the
still not a sentence. Just drop the "when"

http://codereview.appspot.com/218070/diff/29/31#newcode185
doc/go_programming_faq.html:185: This is the intended, correct behaviour. Once
understood, it becomes very
very .... ?

[adg, 2010-03-01 05:06:28]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[rsc, 2010-03-01 05:39:50]

will take a look tomorrow.
heading to bed now.

On Sun, Feb 28, 2010 at 21:06,  <adg@golang.org> wrote:
> Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),
>
> Please take another look.
>
>
> http://codereview.appspot.com/218070/show
>

[iant, 2010-03-01 23:12:40]

LGTM

http://codereview.appspot.com/218070/diff/3011/2008
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/3011/2008#newcode16
doc/go_programming_faq.html:16: Map and slice values are also handles pointing
at other data.  Copying a map or
How about: "Map and slice values are like pointers.  Copying a map...."

http://codereview.appspot.com/218070/diff/3011/2008#newcode39
doc/go_programming_faq.html:39: Defining a method on a value rather is most
useful when defining methods on
s/rather //

http://codereview.appspot.com/218070/diff/3011/2008#newcode200
doc/go_programming_faq.html:200: There is no ternary form in Go. You may use the
following to acheive the same
s/acheive/achieve/

http://codereview.appspot.com/218070/diff/3011/2008#newcode220
doc/go_programming_faq.html:220: no header file or need for forward
declarations.
Perhaps: "Source files can refer to items from different files in the same
package at will; there is no need for forward declarations or a header file."

[gri, 2010-03-01 23:27:46]

FYI.
- Robert

http://codereview.appspot.com/218070/diff/3011/2008
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/3011/2008#newcode11
doc/go_programming_faq.html:11: value to the parameter.  Copying a pointer
value, however, just makes a copy of
This sounds like it is an exception, which it isn't. It might be better to say
something like:

For instance, passing a pointer value is the same as assigning the pointer to a
pointer variable, so a copy of the pointer is made and not of the object it
points to.

(adjust my English as necessary).

http://codereview.appspot.com/218070/diff/3011/2008#newcode16
doc/go_programming_faq.html:16: Map and slice values are also handles pointing
at other data.  Copying a map or
Or perhaps:

Maps and slice value behave like pointers; they are descriptors that contain
pointers to the underlying map or slice data. Thus, copying a map or slice makes
a copy of the descriptor (including the pointer), but not the data the pointer
is referring to.

http://codereview.appspot.com/218070/diff/3011/2008#newcode79
doc/go_programming_faq.html:79: The size of <code>int</code> on 64-bit systems
is consistent with the behaviour
I think we write "behavior" elsewhere. There's another one below. Don't really
care too much.

[adg, 2010-03-02 00:42:12]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[r, 2010-03-02 00:55:38]

http://codereview.appspot.com/218070/diff/2013/3021
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/2013/3021#newcode12
doc/go_programming_faq.html:12: the pointer, not the data it points at.
points to, not points at. you use them both. please be consistent and please use
'to'.

http://codereview.appspot.com/218070/diff/2013/3021#newcode18
doc/go_programming_faq.html:18: slice value doesn't copy the data it points at. 
Copying an interface value
s/at/to/

http://codereview.appspot.com/218070/diff/2013/3021#newcode22
doc/go_programming_faq.html:22: makes a copy of the pointer, but again not the
data it points at.
ditto

http://codereview.appspot.com/218070/diff/2013/3021#newcode43
doc/go_programming_faq.html:43: dereferenced to be used).
why is this parenthesized?

http://codereview.appspot.com/218070/diff/2013/3021#newcode48
doc/go_programming_faq.html:48: only methods which do not need to modify any of
the fields in the struct.  In
a lot of words about efficiency but nothign about why.
there's a semantic difference that really matters.

it's trivial: why do you pass a value to a function by value or by address. if
you can answer that question, the same answer applies to method receivers
because - hey! - they're just arguments.

in other words, it's not a big deal, so don't make it one. reduce it to the
trivium it really is.

http://codereview.appspot.com/218070/diff/2013/3021#newcode82
doc/go_programming_faq.html:82: does not have to be consistent with C/C++, but
it doesn't hurt.
not sure this paragraph is a good idea.

http://codereview.appspot.com/218070/diff/2013/3021#newcode112
doc/go_programming_faq.html:112: Programs that perform a great deal of
concurrent computation should benefit
6g etc. only.

http://codereview.appspot.com/218070/diff/2013/3021#newcode119
doc/go_programming_faq.html:119: Why does using <code>GOMAXPROCS</code> > 1
sometimes make my program slower?</h3>
ditto.

i feel like i'm commenting on an old version.

http://codereview.appspot.com/218070/diff/2013/3021#newcode170
doc/go_programming_faq.html:170: when the goroutine was launched. Compare:
yeah, but why?
just say it: closures share *variables*.

too much example too little explanation

http://codereview.appspot.com/218070/diff/2013/3021#newcode192
doc/go_programming_faq.html:192: other languages (for example, JavaScript).
drop the parenthetical remark

[adg, 2010-03-03 02:17:38]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[rsc, 2010-03-03 02:39:51]

http://codereview.appspot.com/218070/diff/2018/2020
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/2018/2020#newcode5
doc/go_programming_faq.html:5: <h3 id="When_should_I_pass_by_value">
Go through and make sure the id's match, or shorten them.
This could be id="pass_by_value" for example.
These are going to be used all the time to point people
at specific answers, so it will help to keep them short
but still specific.

http://codereview.appspot.com/218070/diff/2018/2020#newcode107
doc/go_programming_faq.html:107: Why does using <code>GOMAXPROCS</code> > 1
sometimes make my program slower
move ? up

http://codereview.appspot.com/218070/diff/2018/2020#newcode107
doc/go_programming_faq.html:107: Why does using <code>GOMAXPROCS</code> > 1
sometimes make my program slower
change > 1 to &gt; 1

http://codereview.appspot.com/218070/diff/2018/2020#newcode252
doc/go_programming_faq.html:252: var int_a = [4][4]int {
run through gofmt to get the standard formatting.
(this isn't it.)
better variable name too (something with mixedCaps
if it needs to be multi-word).

http://codereview.appspot.com/218070/diff/2018/2020#newcode267
doc/go_programming_faq.html:267: var int_a = [4][4]int {
gofmt

http://codereview.appspot.com/218070/diff/2018/2020#newcode280
doc/go_programming_faq.html:280: This slightly versbose syntax is a side-effect
of that choice.
s/versbose/verbose/
s/side-effect/side effect/

[adg, 2010-03-03 03:01:11]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[r, 2010-03-03 04:33:39]

http://codereview.appspot.com/218070/diff/3030/2024
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/3030/2024#newcode37
doc/go_programming_faq.html:37: points to. Otherwise, it is often syntactically
simpler to define the method on
s/syntactically simpler/cleaner/

http://codereview.appspot.com/218070/diff/3030/2024#newcode262
doc/go_programming_faq.html:262: inferred by the compiler. It could be argued
that you should omit
Replace the rest of this answer with:

It seems that the inner [4]int could be inferred, but in general it's hard to
get this sort of thing right.
Some of Go's designers had worked on other languages that derived types
automatically in such expressions, but the special cases that arise can be
messy, especially when interfaces, nil, constant conversions, and such are
involved. It seemed better to require the full type information. That way there
will be no surprises.

http://codereview.appspot.com/218070/diff/3030/2024#newcode267
doc/go_programming_faq.html:267: var intArray = [4][4]int{
drop this example - it's obvious.

http://codereview.appspot.com/218070/diff/3030/2024#newcode277
doc/go_programming_faq.html:277: of named initializer positions and array index
positions only compounds this.
"this": what?

http://codereview.appspot.com/218070/diff/3030/2024#newcode280
doc/go_programming_faq.html:280: This slightly verbose syntax is a side effect
of that choice.
slightly is gratuitous.  "The syntax is a consequence of that decision."

[adg, 2010-03-03 04:53:47]

Hello r, rsc, iant, gri (cc: golang-dev@googlegroups.com),

Please take another look.

[rsc, 2010-03-04 01:37:09]

LGTM

(but wait for other LGTMs to submit)

http://codereview.appspot.com/218070/diff/3032/2032
File doc/go_programming_faq.html (right):

http://codereview.appspot.com/218070/diff/3032/2032#newcode243
doc/go_programming_faq.html:243: <h3 id="Nested_array_verbose"
lowercase nested

[r2, 2010-03-04 01:38:16]

LGTM

[adg, 2010-03-04 01:56:18]

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

First run at a Programming FAQ

Moved a couple of FAQs from the main FAQ, and added some others

R=r, rsc, iant, gri
CC=golang-dev
http://codereview.appspot.com/218070