Grammar and wording changes to 'Basics' page. #1579

Tazzle · 2019-11-13T19:30:52Z

No description provided.

…uence or hierarchy

…ly' is more commonly used to express integration.

… objects have one behaviour, instead of each object having its own behaviour

…wo separate options

…o words may be an expert's subjective opinion

…al space. Add 'as reasonably possible' to have a shorter sentence while retaining same meaning.

…ere is a link to the next page within the sentence, and again directly below the sentence

…ation together

…re not a rule

…nctuation mark

Ichoran

Overall I think the changes make this document quite a bit more readable! Thanks!

Ichoran · 2019-11-13T20:37:31Z

_tour/basics.md


 ```tut:fail
 x = 3 // This does not compile.
 ```

-Types of values can be inferred, but you can also explicitly state the type, like this:
+The type of a value can be omitted and inferred by [type inference](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated:


Being inferred by inference is kind of redundant. Maybe say something like, "When no type is specified, the type is inferred. The type can also be explicitly specifed:"

I take your point but I was aiming this at newcomers to Scala who might want to know what it is inferred by.

They can figure it out easily enough with a link and a suggestive phrase like "type is inferred", no?

Sorry, I was on mobile when I read that so I didn't see the hyperlink you add to "the type is inferred". Sure, that makes sense.

Ichoran · 2019-11-13T20:38:30Z

_tour/basics.md

@@ -74,11 +71,11 @@ Variables are like values, except you can re-assign them. You can define a varia

 ```tut
 var x = 1 + 1
-x = 3 // This compiles because "x" is declared with the "var" keyword.
+x = 3 // This compiles because "x" is declared with the "var" keyword:


This change is incorrect! The comment refers to this line, not the next line which is what the colon suggests! No colon--the original was correct.

Ichoran · 2019-11-13T20:39:27Z

_tour/basics.md

 println(x * x) // 9
 ```

-As with values, you can explicitly state the type if you want:
+As with values, the type of a variable can be omitted and inferred by [type inference](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated:


This should also be rewritten to avoid inferred-by-inference.

Ichoran · 2019-11-13T20:40:44Z

_tour/basics.md

@@ -100,17 +97,17 @@ println({

 ## Functions

-Functions are expressions that take parameters.
+Functions are expressions that have parameters, and take arguments.


This is redundant. Having parameters is equivalent to taking arguments. The original is better. (Also, functions can take zero arguments, so the statement isn't even correct either way, but the new one is worse than the old one.)

Also, although "arguments" is more standard terminology, the parameters are called parameters in Scala, so it's probably better to leave it alone.

I take your point about the functions having zero arguments, but the original statement saying a function can "take" parameters doesn't make sense either.

A function has parameters. When it says functions "take" parameters it sounds like "parameters" can be passed in. Arguments can be passed in, parameters can't.

Fair enough, but I don't think the clarity of the text should rely upon the reader understanding that arguments are the passed-in version of parameters.

If a reader sees "functions can take parameters", they might wonder about the quality, and accuracy of the Scala documentation as a whole.

The information should be made as accurate as possible, regardless of the reader's level of understanding.

I think this a (living) language thing. Some languages call them two different types of parameters; English calls them parameters and arguments.

I'm going to merge the PR regardless, but I lean more towards Rex's side here. I invite anyone interested to submit a followup PR with a different wording that we all like?

Ichoran · 2019-11-13T20:42:51Z

_tour/basics.md

@@ -119,7 +116,7 @@ println(addOne(1)) // 2
 ```
 {% endscalafiddle %}

-Functions may take multiple parameters.
+A function can take multiple arguments:


I am not convinced that parameters should be replaced by arguments given that the nomenclature universally uses the former (e.g. they are "parameter blocks" not "argument blocks").

I can change this to "have" multiple parameters.

Ichoran · 2019-11-13T20:43:01Z

_tour/basics.md

@@ -128,7 +125,7 @@ println(add(1, 2)) // 3
 ```
 {% endscalafiddle %}

-Or it can take no parameters.
+Or no arguments at all:


Again, not convinced of the change

You are correct. I will change this.

Ichoran · 2019-11-13T20:46:11Z

_tour/basics.md

@@ -205,21 +202,23 @@ We will cover classes in depth [later](classes.html).

 ## Case Classes

-Scala has a special type of class called a "case" class.  By default, case classes are immutable and compared by value. You can define case classes with the `case class` keywords.
+Scala has a special type of class called a "case" class. By default, case classes are immutable, and they are compared by value (unlike classes, which are compared by reference). This makes them particularly useful for [pattern matching](https://docs.scala-lang.org/tour/pattern-matching.html#matching-on-case-classes).


This isn't what makes them useful for pattern matching. They are additionally useful for pattern matching because the compiler automatically generates the matcher.

I think I'm reading this as "for pattern matching, they are particularly useful", and you are reading this as "they are useful specifically for pattern matching", so I will change this due to ambiguity, thanks!

I am reading it as, "The qualities I described above is what makes them useful for matching." This is what I object to, because it mostly isn't the reason they're useful for matching.

Ichoran · 2019-11-13T20:49:09Z

_tour/basics.md

@@ -266,17 +265,17 @@ We will cover objects in depth [later](singleton-objects.html).

 ## Traits

-Traits are types containing certain fields and methods.  Multiple traits can be combined.
+Traits are abstract data types containing certain fields and methods. In Scala inheritance, a class can not only inherit from a super class, but also mix in one or more traits.


This is phrased somewhat awkwardly, though the point is good. Maybe something like, "A class can only extend a single other class, but it can extend multiple traits." (Caveat: I'm not sure "extend" is the right word to use.)

I don't know whether extend or mix in is more accurate.

In the Traits page it says "Classes and objects can extend traits", and in the mixins page it says "Mixins are traits which are used to compose a class.", so do you mix in a mixin, or do you extend a mixin?

Ichoran · 2019-11-13T20:54:31Z

_tour/tour-of-scala.md


 ## Scala is functional ##
-Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, it supports [higher-order functions](higher-order-functions.html), it allows functions to be [nested](nested-functions.html), and supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) model algebraic types used in many functional programming languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class.
+Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, it supports [higher-order functions](higher-order-functions.html), it allows functions to be [nested](nested-functions.html), and it supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) model algebraic types are used in many functional programming languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class.


"model algebraic types" is pretty abstruse. While you're making changes, maybe you want to say something like, "...provide the functionality of algebraic types, which are used in many functional programming languages."

The change here is that I added in an extra "it" for "and it supports currying" but this change seems to only show up in the rich diff, unfortunately.

I'm aware--I just think that the "model algebraic types" language (using model as a verb) is so unclear that it ought to be fixed as long as you're making broad improvements here.

SethTisue · 2019-12-06T02:19:44Z

@Tazzle interested in getting this over the finish line...?

Tazzle · 2019-12-06T08:33:37Z

@Tazzle interested in getting this over the finish line...?

Tazzle · 2019-12-06T08:35:00Z

@Tazzle interested in getting this over the finish line...?

@SethTisue sure! I didn't realise my first PR had been merged. Will get onto this today.

SethTisue · 2019-12-15T02:58:52Z

Thanks Tazzle for the good work here! And thanks Rex for the useful review feedback.

Tazzle added 30 commits November 13, 2019 12:53

Add colon before list

e767bbd

Change ordered list to unordered list as items do not represent a seq…

212dca7

…uence or hierarchy

Change 'either' to 'whichever'

e52b959

Capitalise first letter of item in a list

85af57b

Add 'by' to clarifymeaning

702e32f

Add colon before a list

1d8fe41

Add missing word, and add a comma and a 'for' for clarity

7f4efb3

Change html lists to markdown for consistency with other lists

af2b2e3

Change 'set up' verb to 'setup' adjective

629075a

Change 'smoothly' integrates to 'seamlessly' integrates, as 'seamless…

761ca7d

…ly' is more commonly used to express integration.

Flesh out the word 'that', to provide more clarity

b47dd26

Change 'behavior' to 'behaviors' for clarity, as it may seem like all…

8b1fdce

… objects have one behaviour, instead of each object having its own behaviour

Change sentence slightly to clarify that subclassing and mixins are t…

9d9a2b5

…wo separate options

Add it for consistency with the rest of the list

1a4956b

Add missing word

96711b4

Capitalise first letter of items in a list

46d0daf

Change use of 'easy' and 'smoothly' to 'straightforward', as these tw…

d2e90e0

…o words may be an expert's subjective opinion

Change 'smooth' to 'seamless'

06ab742

Change 'close' to 'closely', as 'close' relates to location in physic…

22b3f49

…al space. Add 'as reasonably possible' to have a shorter sentence while retaining same meaning.

Change grammar; should be 'as' instead of 'with'

875ce74

Remove reference to contents menu to prevent information overload; th…

5892a23

…ere is a link to the next page within the sentence, and again directly below the sentence

Add a colon directly preceding a list

41d2729

Remove unnecessary comma from list item

e38d984

Add missing word

4991195

Add a colon before a list

e0ec662

Change words to increase clarity

ddf423d

Rearrange wording to increase clarity. Italicise 'ScalaFiddle'

627a552

Italicise 'ScalaFiddle'. Reorganise sentences to group similar inform…

0f9e44c

…ation together

Add a colon when introducing a code example

b03bf63

Add words for clarity and consistency

7d66392

Tazzle added 17 commits November 13, 2019 17:38

Add more clarity around type inference

26e491b

Add more clarity around type inference

8e1428a

Update description of scala functions.

c692abc

Add clarity to anonymous function description

2567d1c

Change 'parameter' to 'argument'

6902608

Change 'parameter' to 'argument'

25bfca3

Add parenthesis around 's' to clarify that multiple parameter lists a…

121e24e

…re not a rule

Remove redundancy of having the word 'colon' followed by the colon pu…

d5ace9e

…nctuation mark

Clarify the description of 'Unit'

3279cbf

Flesh out the definition of case classes

52e065b

Add missing word

ba03182

Add clarity to case class comparison

4c50787

Add missing word

1671d4e

Flesh out the description of traits for clarity

48f1e8f

Clarify the definition of a main method

675528b

Tidy up: add commas and clarifications

bcf565c

Remove contractions

b13084c

Ichoran suggested changes Nov 13, 2019

View reviewed changes

Tazzle closed this Dec 6, 2019

Tazzle reopened this Dec 6, 2019

Tazzle and others added 2 commits December 6, 2019 14:17

Make changes requested in PR comments

7502ee9

Merge branch 'master' into basics

006dafc

SethTisue merged commit 5a7b431 into scala:master Dec 15, 2019

Grammar and wording changes to 'Basics' page. #1579

Grammar and wording changes to 'Basics' page. #1579

Uh oh!

Conversation

Tazzle commented Nov 13, 2019

Uh oh!

Ichoran left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ichoran Nov 13, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tazzle Nov 14, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SethTisue commented Dec 6, 2019

Uh oh!

Tazzle commented Dec 6, 2019

Uh oh!

Tazzle commented Dec 6, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SethTisue commented Dec 15, 2019

Uh oh!

Uh oh!

Ichoran Nov 13, 2019 •

edited

Loading

Tazzle Nov 14, 2019 •

edited

Loading

Tazzle commented Dec 6, 2019 •

edited

Loading