Commit 5c4806a7 authored by Alan Crosswell's avatar Alan Crosswell Committed by Lauren Ko

Remove demotivating uses of "just" (#653)

* Remove demotivating uses of "just"

per "How Not to Demotivate Your Learners" at https://carpentries.github.io/instructor-training/08-motivation/index.html

* remove a couple cases of demotivating language

* Wording improvements per @maxim-belkin review
also add rubber ducking reference.

* wording clarifications
- Compare to the previous lesson's string rather than for loop
- grammar plural agreement
parent 63dee896
......@@ -57,7 +57,7 @@ weight_kg = 60
{: .language-python}
From now on, whenever we use `weight_kg`, Python will substitute the value we assigned to
it. In essence, **a variable is just a name for a value**.
it. In layman's terms, **a variable is a name for a value**.
In Python, variable names:
......@@ -84,7 +84,7 @@ weight_kg = 60.0
~~~
{: .language-python}
And to create a string we simply have to add single or double quotes around some text, for example:
And to create a string, we add single or double quotes around some text, for example:
~~~
weight_kg_text = 'weight in kilograms:'
......@@ -279,9 +279,9 @@ when there's nothing interesting after the decimal point.
Our call to `numpy.loadtxt` read our file
but didn't save the data in memory.
To do that,
we need to assign the array to a variable. Just as we can assign a single value to a variable, we
can also assign an array of values to a variable using the same syntax. Let's re-run
`numpy.loadtxt` and save the returned data:
we need to assign the array to a variable. In a similar manner to how we assign a single
value to a variable, we can also assign an array of values to a variable using the same syntax.
Let's re-run `numpy.loadtxt` and save the returned data:
~~~
data = numpy.loadtxt(fname='inflammation-01.csv', delimiter=',')
......@@ -365,7 +365,7 @@ print(data.shape)
{: .output}
The output tells us that the `data` array variable contains 60 rows and 40 columns. When we
created the variable `data` to store our arthritis data, we didn't just create the array; we also
created the variable `data` to store our arthritis data, we did not only create the array; we also
created information about the array, called [members]({{ page.root }}/reference/#member) or
attributes. This extra information describes `data` in the same way an adjective describes a noun.
`data.shape` is an attribute of `data` which describes the dimensions of `data`. We use the same
......@@ -471,7 +471,7 @@ print(data[5:10, 0:10])
We also don't have to include the upper and lower bound on the slice. If we don't include the lower
bound, Python uses 0 by default; if we don't include the upper, the slice runs to the end of the
axis, and if we don't include either (i.e., if we just use ':' on its own), the slice includes
axis, and if we don't include either (i.e., if we use ':' on its own), the slice includes
everything:
~~~
......
......@@ -32,7 +32,7 @@ word = 'lead'
~~~
{: .language-python}
In Python, a string is just an ordered collection of characters, so every
In Python, a string is basically an ordered collection of characters, and every
character has a unique number associated with it -- its index. This means that
we can access characters in a string using their indices.
For example, we can get the first character of the word `'lead'`, by using
......@@ -57,7 +57,7 @@ d
This is a bad approach for three reasons:
1. **Not scalable**. Imagine you need to print characters of a string that is hundreds
of letters long. It might be easier just to type them in manually.
of letters long. It might be easier to type them in manually.
2. **Difficult to maintain**. If we want to decorate each printed character with an
asterix or any other character, we would have to change four lines of code. While
......@@ -163,10 +163,8 @@ of the loop body (e.g. `end for`); what is indented after the `for` statement be
>
>
> In the example above, the loop variable was given the name `char` as a mnemonic;
> it is short for 'character'.
> We can choose any name we want for variables. We might just as easily have chosen the name
> `banana` for the loop variable, as long as we use the same name when we invoke the variable inside
> the loop:
> it is short for 'character'. We can choose any name we want for variables.
> We can even call our loop variable `banana`, as long as we use this name consistently:
>
> ~~~
> word = 'oxygen'
......@@ -222,7 +220,7 @@ since there is nothing left in `'aeiou'` for Python to process,
the loop finishes
and the `print` statement on line 4 tells us our final answer.
Note that a loop variable is just a variable that's being used to record progress in a loop.
Note that a loop variable is a variable that's being used to record progress in a loop.
It still exists after the loop is over,
and we can re-use variables previously defined as loop variables as well:
......
......@@ -20,8 +20,7 @@ list[2:9]), in the same way as strings and arrays."
- "Strings are immutable (i.e., the characters in them cannot be changed)."
---
Just as a `for` loop is a way to do operations many times,
a list is a way to store many values.
Similar to a string that can contain many characters, a list is a container that can store many values.
Unlike NumPy arrays,
lists are built into the language (so we don't have to load a library
to use them).
......@@ -167,7 +166,7 @@ does not.
{: .callout}
> ## Nested Lists
> Since lists can contain any Python variable, it can even contain other lists.
> Since a list can contain any Python variables, it can even contain other lists.
>
> For example, we could represent the products in the shelves of a small grocery shop:
>
......@@ -305,9 +304,6 @@ odds: [1, 3, 5, 7]
~~~
{: .output}
This is different from how variables worked in lesson 1, and more similar to how a spreadsheet
works.
> ## Turn a String Into a List
>
> Use a for-loop to convert the string "hello" into a list of letters:
......
......@@ -16,9 +16,9 @@ keypoints:
- "An error having to do with the 'grammar' or syntax of the program is called a `SyntaxError`.
If the issue has to do with how the code is indented,
then it will be called an `IndentationError`."
- "A `NameError` will occur if you use a variable that has not been defined,
either because you meant to use quotes around a string, you forgot to define the variable,
or you just made a typo."
- "A `NameError` will occur when trying to use a variable that does not exist. Possible causes are
that a variable definition is missing, a variable reference differs from its definition
in spelling or capitalization, or the code contains a string that is missing quotes around it."
- "Containers like lists and strings will generate errors if you try to access items
in them that do not exist. This type of error is called an `IndexError`."
- "Trying to read a file that does not exist will give you an `FileNotFoundError`.
......@@ -97,10 +97,10 @@ the program encountered an error on Line 6, when it tried to run the code `print
> Sometimes, you might see a traceback that is very long
> -- sometimes they might even be 20 levels deep!
> This can make it seem like something horrible happened,
> but really it just means that your program called many functions before it ran into the error.
> Most of the time,
> you can just pay attention to the bottom-most level,
> which is the actual place where the error occurred.
> but the length of the error message does not reflect severity, rather,
> it indicates that your program called many functions before it encountered the error.
> Most of the time, the actual place where the error occurred is at the bottom-most level,
> so you can skip down the traceback to the bottom.
{: .callout}
So what error did the program actually encounter?
......@@ -115,7 +115,7 @@ if you fix the error,
but encounter a new one,
you can tell that the error changed.
Additionally,
sometimes just knowing *where* the error occurred is enough to fix it,
sometimes knowing *where* the error occurred is enough to fix it,
even if you don't entirely understand the message.
If you do encounter an error you don't recognize,
......@@ -144,7 +144,7 @@ to some extent it might be ambiguous if there should be a sentence break or not
People can typically figure out what is meant by text with no punctuation,
but people are much smarter than computers.
If Python doesn't know how to read the program,
it will just give up and inform you with an error.
it will give up and inform you with an error.
For example:
~~~
......@@ -270,7 +270,7 @@ NameError: name 'hello' is not defined
~~~
{: .error}
The second is that you just forgot to create the variable before using it.
The second reason is that you might be trying to use a variable that does not yet exist.
In the following example,
`count` should have been defined (e.g., with `count = 0`) before the for loop:
......@@ -394,10 +394,10 @@ One reason for receiving this error is that you specified an incorrect path to t
For example,
if I am currently in a folder called `myproject`,
and I have a file in `myproject/writing/myfile.txt`,
but I try to just open `myfile.txt`,
but I try to open `myfile.txt`,
this will fail.
The correct path would be `writing/myfile.txt`.
It is also possible (like with `NameError`) that you just made a typo.
It is also possible that the file name or its path contains a typo.
A related issue can occur if you use the "read" flag instead of the "write" flag.
Python will not give you an error if you try to open a file for writing
......
......@@ -121,8 +121,8 @@ are almost never worthwhile.
If it takes 20 minutes for the bug to surface,
we can only do three experiments an hour.
That doesn't just mean we'll get less data in more time:
we're also more likely to be distracted by other things as we wait for our program to fail,
This means that we'll get less data in more time and that
we're more likely to be distracted by other things as we wait for our program to fail,
which means the time we *are* spending on the problem is less focused.
It's therefore critical to *make it fail fast*.
......@@ -206,8 +206,10 @@ and we're better able to give them the information they need to be useful.
And speaking of help:
if we can't find a bug in 10 minutes,
we should *be humble* and ask for help.
Just explaining the problem aloud is often useful,
Explaining the problem to someone else is often useful,
since hearing what we're thinking helps us spot inconsistencies and hidden assumptions.
If you don't have someone nearby to share your problem description with, get a
[rubber duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging)!
Asking for help also helps alleviate confirmation bias.
If we have just spent an hour writing a complicated program,
......
......@@ -440,7 +440,7 @@ $ python ../code/readings_03.py small-01.csv small-02.csv
The next step is to teach our program to pay attention to the `--min`, `--mean`, and `--max` flags.
These always appear before the names of the files,
so we could just do this:
so we could do this:
~~~
$ cat ../code/readings_04.py
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment