gh-107017: Rework the Fibonacci example #107132
Conversation
Rework the example to be simple to follow and also the concepts needed for that are now explained one by one with their own shorter examples.
Doc/tutorial/introduction.rst
Outdated
|
|
||
| A *multiple assignment* of variables us allows to set values of more than one | ||
| variable on a single line. Notice that if the value assignment is a | ||
| expression, it is first evaluated and then assigned.:: |
There was a problem hiding this comment.
.:: will produce a full-stop and a colon:
.:
One or the other. I suggest losing the full-stop.
Doc/tutorial/introduction.rst
Outdated
| ------------------ | ||
|
|
||
| The :keyword:`while` loop is example of a repeating cycle. It performs | ||
| a block of code over as long as the condition (in example: ``a < 10``) is |
There was a problem hiding this comment.
"in example" > "for example"
There was a problem hiding this comment.
What I wanted to say is that "in the example below the condition is the following expression a < 10", but that is no longer present in the examples. I will rework that.
Doc/tutorial/introduction.rst
Outdated
| >>> count # when count reached value of 5, while loop finished | ||
| 5 | ||
|
|
||
| Note that block inside the while loop, or *body* of the loop is *indented*. |
There was a problem hiding this comment.
I suggest using while, to draw attention to it.
Doc/tutorial/introduction.rst
Outdated
| the Python shell, you need to type a tab or space(s) for each indented line. | ||
| Each line within a block must be indented by the same amount. | ||
| When we want to exit the indented block of code in the Python shell, we must | ||
| follow it by a blank line to indicate its completion. This way, parser knows |
Doc/tutorial/introduction.rst
Outdated
| Each line within a block must be indented by the same amount. | ||
| When we want to exit the indented block of code in the Python shell, we must | ||
| follow it by a blank line to indicate its completion. This way, parser knows | ||
| we have finished typing the last line).:: |
There was a problem hiding this comment.
Again, here we have a full-stop and a colon in the output.
| ... print(count, end=' ') # end the output of print() with a whitespace | ||
| ... count = count - 1 # lower the value by one with each repetition | ||
| ... | ||
| 10 9 8 7 6 |
| ... print('', a, '', end='->') | ||
| ... a, b = b, a+b | ||
| ... | ||
| 0 -> 1 -> 1 -> 2 -> 3 -> 5 -> 8 -> 13 -> 21 -> 34 -> 55 -> 89 -> 144 -> |
There was a problem hiding this comment.
And I like the way that the example illustrates the value of using end - no need to explain, the example does it much more effectively. This will stick in someone's mind.
Fix parts where a paragraph ended both with full-stop and colon. Added new paragraph, where example of simple loop is explained in detail. Plus warning about indefinite loops.
|
|
||
| >>> a, b = 0, 1 | ||
| >>> while a < 150: | ||
| ... print('', a, '', end='->') |
There was a problem hiding this comment.
I understand that this utilities the print sep param, however this is nor explained nor inferred, so to a beginner it may be confusing
Perhaps it could be beneficial to show off f-strings like
| ... print('', a, '', end='->') | |
| ... print(f'{a} ->', end='') |
Or to keep end as ->
| ... print('', a, '', end='->') | |
| ... print(f'{a} ', end="->") |
There was a problem hiding this comment.
I very strongly prefer the original print('', a, '', end='->'), which reduces the punctuation the learner has to deal with to a minimum, and emphasises instead the connection between more easily assimilated things, like the English word "end" and the "arrow" ("->").
Showing off f-strings while demonstrating a different functionality introduces unnecessary cognitive burden. Two different kinds of quotes and two different kinds of brackets requires a lot of parsing and stopping. I don't think this is the right solution here.
There was a problem hiding this comment.
My reasoning: As this is an Introduction chapter, I wanted to keep the number of introduced concepts to the minimum. There are ways to code this better, but it is not formally wrong. The default separator is already shown in the example above and this just builds on that, so it's hopefully not confusing to the reader.
Doc/tutorial/introduction.rst
Outdated
| >>> count = 10 | ||
| >>> while count > 5: | ||
| ... print(count, end=' ') # end the output of print() with a whitespace | ||
| ... count = count - 1 # lower the value by one with each repetition |
There was a problem hiding this comment.
| ... count = count - 1 # lower the value by one with each repetition | |
| ... count = count - 1 # decrement the value each iteration |
There was a problem hiding this comment.
I would strongly prefer "decrease the value by one".
The reason is that many people will not be familiar with the word "decrement", it's used very little in English outside technical contexts.
Doc/tutorial/introduction.rst
Outdated
| expression, it is first evaluated and then assigned:: | ||
|
|
||
| >>> a, b = 1, 5 # multiple assignment of two variables | ||
| >>> a | ||
| 0 |
There was a problem hiding this comment.
Is this a doctest bug?
Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>
Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>
More precise and clearer wording. Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>
Doc/tutorial/introduction.rst
Outdated
| >>> count = 10 | ||
| >>> while count > 5: | ||
| ... print(count, end=' ') # end the output of print() with a whitespace | ||
| ... count = count - 1 # lower the value by one with each repetition |
There was a problem hiding this comment.
I would strongly prefer "decrease the value by one".
The reason is that many people will not be familiar with the word "decrement", it's used very little in English outside technical contexts.
|
|
||
| >>> a, b = 0, 1 | ||
| >>> while a < 150: | ||
| ... print('', a, '', end='->') |
There was a problem hiding this comment.
I very strongly prefer the original print('', a, '', end='->'), which reduces the punctuation the learner has to deal with to a minimum, and emphasises instead the connection between more easily assimilated things, like the English word "end" and the "arrow" ("->").
Showing off f-strings while demonstrating a different functionality introduces unnecessary cognitive burden. Two different kinds of quotes and two different kinds of brackets requires a lot of parsing and stopping. I don't think this is the right solution here.
Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>
lower the value -> decrease the value
Doc/tutorial/introduction.rst
Outdated
| 0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987, | ||
| 4 | ||
|
|
||
| Function argumets |
Doc/tutorial/introduction.rst
Outdated
| Function argumets | ||
| ----------------- | ||
|
|
||
| We already know :func:`print` function, that writes the value of the |
There was a problem hiding this comment.
We already know the print function ?
| We can use Python for more complex tasks than adding two and two together. | ||
| For instance, we can compute the numbers of the | ||
| `Fibonacci series <https://en.wikipedia.org/wiki/Fibonacci_number>`_. | ||
| To do that we need to utilize three following concepts. |
There was a problem hiding this comment.
| To do that we need to utilize three following concepts. | |
| To do that we need to use the three following concepts. |
Let's use the plain English "use" instead of "utilize".
| Multiple Assignment | ||
| ------------------- | ||
|
|
||
| A *multiple assignment* of variables us allows to set values of more than one |
There was a problem hiding this comment.
| A *multiple assignment* of variables us allows to set values of more than one | |
| A *multiple assignment* of variables us allows to set the values of more than one |
| ------------------- | ||
|
|
||
| A *multiple assignment* of variables us allows to set values of more than one | ||
| variable on a single line. Notice that if the value assignment is a |
There was a problem hiding this comment.
| variable on a single line. Notice that if the value assignment is a | |
| variable on a single line. Notice that if the value assignment is an |
| Repeating our code | ||
| ------------------ | ||
|
|
||
| The :keyword:`while` loop is example of a repeating cycle. It performs |
There was a problem hiding this comment.
| The :keyword:`while` loop is example of a repeating cycle. It performs | |
| The :keyword:`while` loop is an example of a repeating cycle. It performs |
| in this case, ``count < 5``. To ensure that the loop finishes, we must make | ||
| sure that the condition is *not fulfilled* at a certain step. Otherwise, the | ||
| code would repeat indefinitely. To achieve that, we can increase the value | ||
| of count. As soon as the variable ``count`` reaches the value 5, the |
There was a problem hiding this comment.
| of count. As soon as the variable ``count`` reaches the value 5, the | |
| of ``count``. As soon as the variable ``count`` reaches the value 5, the |
| of count. As soon as the variable ``count`` reaches the value 5, the | ||
| condition will be ``False``:: | ||
|
|
||
| >>> count = 0; # define variable to which we will be adding 1 in a loop |
There was a problem hiding this comment.
| >>> count = 0; # define variable to which we will be adding 1 in a loop | |
| >>> count = 0 # define variable to which we will be adding 1 in a loop |
| >>> while count < 5: count = count + 1 # hit enter one more time to start the loop | ||
| ... | ||
| >>> count # when count reached value of 5, while loop finished | ||
| 5 | ||
|
|
||
| Note that block inside the ``while`` loop, or *body* of the loop is *indented*. |
There was a problem hiding this comment.
The example above uses a one-liner: while count < 5: count = count + 1
Let's use indentation in the example, to match the text. Something like this?
| >>> while count < 5: count = count + 1 # hit enter one more time to start the loop | |
| ... | |
| >>> count # when count reached value of 5, while loop finished | |
| 5 | |
| Note that block inside the ``while`` loop, or *body* of the loop is *indented*. | |
| >>> while count < 5: | |
| ... count = count + 1 # hit enter one more time to start the loop | |
| ... | |
| >>> count # when count reached value of 5, while loop finished | |
| 5 | |
| Note that block inside the ``while`` loop, or *body* of the loop is *indented*. |
| parentheses ``()``. In simplest form, like ``print(a, b)``, the arguments | ||
| are positional, meaning the function processes them in the same order |
There was a problem hiding this comment.
| parentheses ``()``. In simplest form, like ``print(a, b)``, the arguments | |
| are positional, meaning the function processes them in the same order | |
| parentheses ``()``. In its simplest form, like ``print(a, b)``, the arguments | |
| are positional, meaning the function processes them in the same order |
|
Thanks for working on this! As compared to the version on the left hand side, I found presenting all the concepts up front in detailed sections a little intimidating. I preferred seeing the four lines we're building towards first, and then an explanation of what's going on. |
|
The following commit authors need to sign the Contributor License Agreement: |
Rework the example to be simple to follow and also the concepts needed for that are now explained one by one with their own shorter examples.
Needs proofread. Please comment with your ideas for improvement.
📚 Documentation preview 📚: https://cpython-previews--107132.org.readthedocs.build/