code review 148580043: spec: define "variable"

spec: define "variable"

Fixes issue 8496.

[gri, 2014-10-06 19:30:05]

Hello r@golang.org, rsc@golang.org, iant@golang.org, ken@golang.org (cc:
golang-codereviews@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go/

[gri, 2014-10-14 20:03:46]

gentle ping

On Mon, Oct 6, 2014 at 12:30 PM, <gri@golang.org> wrote:

> Reviewers: r, rsc, iant, ken2,
>
> Message:
> Hello r@golang.org, rsc@golang.org, iant@golang.org, ken@golang.org (cc:
> golang-codereviews@googlegroups.com),
>
> I'd like you to review this change to
> https://code.google.com/p/go/
>
>
> Description:
> spec: define "variable"
>
> Please review this at https://codereview.appspot.com/148580043/
>
> Affected files (+79, -25 lines):
>   M doc/go_spec.html
>
>
>

[r, 2014-10-14 20:49:05]

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode655
doc/go_spec.html:655: <i><a href="#Types">variable type</a></i>.
variable's type

(variable is also an adjective, so variable type is ambiguous)

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode667
doc/go_spec.html:667: allocates storage for a variable at run-time.
s/run-time/run time/

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode685
doc/go_spec.html:685: which is the actual type of the value stored in the
variable at run time
the type of a variable is always the type of the value stored in it at run time.
 this isn't definitive.

maybe, "which is the concrete type of the value assigned to the interface
variable at run time"

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode686
doc/go_spec.html:686: (unless the value is the predeclared identifier
<code>nil</code>
s/$/,/

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode691
doc/go_spec.html:691: the dynamic type is always the static type.
delete this sentence. it's redundant and we haven't said what a dynamic type
means for a non-interface variable

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode696
doc/go_spec.html:696: var v *T           // v has value nil, static type *T, and
no dynamic type
delete "and no dynamic type?

[gri, 2014-10-14 20:56:05]

PTAL

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode655
doc/go_spec.html:655: <i><a href="#Types">variable type</a></i>.
On 2014/10/14 20:49:05, r wrote:
> variable's type
> 
> (variable is also an adjective, so variable type is ambiguous)

Done.

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode667
doc/go_spec.html:667: allocates storage for a variable at run-time.
On 2014/10/14 20:49:05, r wrote:
> s/run-time/run time/

Done.

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode685
doc/go_spec.html:685: which is the actual type of the value stored in the
variable at run time
On 2014/10/14 20:49:05, r wrote:
> the type of a variable is always the type of the value stored in it at run
time.
>  this isn't definitive.
> 
> maybe, "which is the concrete type of the value assigned to the interface
> variable at run time"

Done.

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode686
doc/go_spec.html:686: (unless the value is the predeclared identifier
<code>nil</code>
On 2014/10/14 20:49:05, r wrote:
> s/$/,/

Done.

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode691
doc/go_spec.html:691: the dynamic type is always the static type.
On 2014/10/14 20:49:05, r wrote:
> delete this sentence. it's redundant and we haven't said what a dynamic type
> means for a non-interface variable

Done.

https://codereview.appspot.com/148580043/diff/60001/doc/go_spec.html#newcode696
doc/go_spec.html:696: var v *T           // v has value nil, static type *T, and
no dynamic type
On 2014/10/14 20:49:05, r wrote:
> delete "and no dynamic type?

Done.

[rsc, 2014-10-16 14:58:33]

LGTM

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode654
doc/go_spec.html:654: The set of permissible values is determined by the
I think you can delay this sentence until the type paragraph below.
And then maybe you don't need to italicize 'variable's', just 'type'.

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode701
doc/go_spec.html:701: A variable value is retrieved by referring to the variable
in an
s/variable/variable's/

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode704
doc/go_spec.html:704: If no assignment has taken place yet, the variable value
is
s/variable/variable's/
again on next line
or make the variable the subject and use a pronoun:

If a variable has not yet been assigned a value, its value is the zero value for
its type.

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode5482
doc/go_spec.html:5482: of the storage location.
s/ location//

[gri, 2014-10-16 17:40:02]

PTAL

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode654
doc/go_spec.html:654: The set of permissible values is determined by the
On 2014/10/16 14:58:33, rsc wrote:
> I think you can delay this sentence until the type paragraph below.
> And then maybe you don't need to italicize 'variable's', just 'type'.

I've tried a few combinations but I think leaving it up here is better. It ties
the variable, value, and type together better. If I move it to the static type
section, it's a bit too late for the structured variables, and if I move it to
the structured variables section, it's not so well connected to the value.

Fixed <i>.

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode701
doc/go_spec.html:701: A variable value is retrieved by referring to the variable
in an
On 2014/10/16 14:58:33, rsc wrote:
> s/variable/variable's/

Done.

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode704
doc/go_spec.html:704: If no assignment has taken place yet, the variable value
is
On 2014/10/16 14:58:33, rsc wrote:
> s/variable/variable's/
> again on next line
> or make the variable the subject and use a pronoun:
> 
> If a variable has not yet been assigned a value, its value is the zero value
for
> its type.

Done.

https://codereview.appspot.com/148580043/diff/80001/doc/go_spec.html#newcode5482
doc/go_spec.html:5482: of the storage location.
On 2014/10/16 14:58:33, rsc wrote:
> s/ location//

Done.

[r, 2014-10-16 17:50:06]

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode659
doc/go_spec.html:659: A <a href="#Variable_declarations">Variable
declaration</a>,
s/Variable/variable/
s/,//

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode660
doc/go_spec.html:660: or&mdash;for function parameters and results&mdash;the
signature
change the mdashes to commas

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode665
doc/go_spec.html:665: Calling the built-in function <a
href="#Allocation"><code>new</code></a>,
s/,//

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode665
doc/go_spec.html:665: Calling the built-in function <a
href="#Allocation"><code>new</code></a>,
so does make, but you can't indirect to it

[gri, 2014-10-16 17:55:06]

PTAL

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode659
doc/go_spec.html:659: A <a href="#Variable_declarations">Variable
declaration</a>,
On 2014/10/16 17:50:06, r wrote:
> s/Variable/variable/
> s/,//

Done.

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode660
doc/go_spec.html:660: or&mdash;for function parameters and results&mdash;the
signature
On 2014/10/16 17:50:06, r wrote:
> change the mdashes to commas

Done.

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode665
doc/go_spec.html:665: Calling the built-in function <a
href="#Allocation"><code>new</code></a>,
On 2014/10/16 17:50:05, r wrote:
> s/,//

Done.

https://codereview.appspot.com/148580043/diff/100001/doc/go_spec.html#newcode665
doc/go_spec.html:665: Calling the built-in function <a
href="#Allocation"><code>new</code></a>,
On 2014/10/16 17:50:06, r wrote:
> so does make, but you can't indirect to it

make creates/initializes a value - it does not allocate a variable

[iant, 2014-10-16 18:51:01]

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode661
doc/go_spec.html:661: of a <a href="#Function_declarations">function
declaration</a>
Do you need to also refer to method declarations?

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode662
doc/go_spec.html:662: or <a href="#Function_literals">function literal</a>
reserves
I think you need a comma before "reserves".

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode667
doc/go_spec.html:667: allocates storage for a variable at run time.
It's hard to find this fully satisfactory.  Here you are saying allocates
storage at run time, as though that is slightly different from what you said in
the preceding sentence.  But function parameters and results, and for that
matter variable declarations within functions, also allocate storage at run
time.

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode683
doc/go_spec.html:683: an element of a structured variable, respectively.
"Respectively" to what?  I think you can just omit ", respectively" here.

[gri, 2014-10-16 19:45:11]

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode661
doc/go_spec.html:661: of a <a href="#Function_declarations">function
declaration</a>
On 2014/10/16 18:51:01, iant wrote:
> Do you need to also refer to method declarations?

A method is a function with a receiver, per the spec. So I think this is ok.

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode662
doc/go_spec.html:662: or <a href="#Function_literals">function literal</a>
reserves
On 2014/10/16 18:51:01, iant wrote:
> I think you need a comma before "reserves".

I let you and r battle this one out since I am not a native speaker. I'm
guessing both are ok.

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode667
doc/go_spec.html:667: allocates storage for a variable at run time.
On 2014/10/16 18:51:00, iant wrote:
> It's hard to find this fully satisfactory.  Here you are saying allocates
> storage at run time, as though that is slightly different from what you said
in
> the preceding sentence.  But function parameters and results, and for that
> matter variable declarations within functions, also allocate storage at run
> time.

Agreed, but it's hard to be fully precise w/o being pedantic. That's why I am
saying here "allocates" while in the previous section "reserves". The
"reservation" happens at compile (declaration) time, while the allocation
happens at run-time in both cases. Even parameters may be copied into the heap
if there address is taken.

Happy to reformulate if you have a reasonably simple suggestion.

I think here it's not so important what the mechanics are. It's more important
to make it clear that these unnamed allocated locations behave like variables.

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode683
doc/go_spec.html:683: an element of a structured variable, respectively.
On 2014/10/16 18:51:00, iant wrote:
> "Respectively" to what?  I think you can just omit ", respectively" here.

Respective to how the variable was created. But fine, left away.

Done.

[r, 2014-10-16 19:57:56]

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html
File doc/go_spec.html (right):

https://codereview.appspot.com/148580043/diff/120001/doc/go_spec.html#newcode662
doc/go_spec.html:662: or <a href="#Function_literals">function literal</a>
reserves
On 2014/10/16 19:45:11, gri wrote:
> On 2014/10/16 18:51:01, iant wrote:
> > I think you need a comma before "reserves".
> 
> I let you and r battle this one out since I am not a native speaker. I'm
> guessing both are ok.

comma permitted but not necessary. leave it out because it's not necessary.

[r, 2014-10-16 19:59:36]

LGTM

[iant, 2014-10-16 21:19:27]

LGTM

[gri, 2014-10-16 22:08:56]

*** Submitted as https://code.google.com/p/go/source/detail?r=3e5d0270f09e ***

spec: define "variable"

Fixes issue 8496.

LGTM=rsc, r, iant
R=r, rsc, iant, ken
CC=golang-codereviews
https://codereview.appspot.com/148580043

[gobot, 2014-10-16 22:11:31]

This CL appears to have broken the linux-386-clang builder.
See http://build.golang.org/log/708eb603dd5805c20116f4fd2eab0fcc5349ef00