Improve the "introduction" page of the tutorial

[ezio-melotti]

BPO	14097
Nosy	@akuchling, @birkenfeld, @rhettinger, @terryjreedy, @ezio-melotti, @merwok, @bitdancer, @cjerdonek, @zware, @andy-maier
Files	issue14097.diff: Patch against 2.7. issue14097-1.diff: Work in progress patch against 3.2. issue14097-2.diff: Patch against 3.3. issue14097-3.diff issue14097-2.7.diff: Backport of 796d1371605d and subsequent changes

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2014-07-01.19:37:45.742>
created_at = <Date 2012-02-23.05:37:53.227>
labels = ['type-feature', 'docs']
title = 'Improve the "introduction" page of the tutorial'
updated_at = <Date 2014-07-02.16:27:46.427>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2014-07-02.16:27:46.427>
actor = 'zach.ware'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2014-07-01.19:37:45.742>
closer = 'zach.ware'
components = ['Documentation']
creation = <Date 2012-02-23.05:37:53.227>
creator = 'ezio.melotti'
dependencies = []
files = ['24622', '28130', '29649', '30312', '35414']
hgrepos = []
issue_num = 14097
keywords = ['patch']
message_count = 31.0
messages = ['154051', '154092', '154117', '154118', '154156', '154159', '154192', '154201', '154315', '154381', '154382', '154400', '176423', '185781', '188216', '188232', '189606', '189607', '189608', '189631', '189633', '189634', '189638', '192665', '219409', '222051', '222056', '222057', '222071', '222112', '222113']
nosy_count = 13.0
nosy_names = ['akuchling', 'georg.brandl', 'rhettinger', 'terry.reedy', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'chris.jerdonek', 'docs@python', 'tshepang', 'python-dev', 'zach.ware', 'andymaier']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14097'
versions = ['Python 2.7']

[ezio-melotti]

I was reading the "introduction" page of the tutorial [0], and noticed a few things that could be improved:
 1) the first paragraph is a bit confusing, showing a simple example and explaining what the >>> is would be better;
 2) comments can be introduced later too, they are not really necessary at the beginning;
 3) the first example is supposed to introduce numbers and basic operations, but it's still going on with the comments;
 4) the note about floating point issues is not so relevant anymore nowadays, so it could be (re)moved;
 5) "A value can be assigned to several variables simultaneously:" is not technically correct;
 6) "Variables must be “defined” (assigned a value) before they can be used" this might be improved too;
 7) almost half of the section about numbers goes on explaining complex numbers.  This is totally unnecessary here, I think that mentioning them and maybe showing a simple example is more than enough.  Another option is to make a subsection with a note that says that the section can be skipped;
 8) the examples in this part lack some space (e.g. "a=3.0+4.0j");
 9) the print() function could get a better introduction and used in the first set of string examples;
 10) suggesting to use continuation lines with a trailing \ in string literals is not a good idea, it's better to use """...""" or implicit concatenation inside ();
 11) "Degenerate slice indices are handled gracefully" it might be better to show that it's not the same for "non-slice" indices;
 12) the "About Unicode" section could link to the Unicode HOWTO;
 13) while it's true that lists can contain different types of object, they usually shouldn't;
 14) while the "while" example is good (it first shows a piece of code and then explains what it does), I would introduce the "if" and the "for" first.  The "while" is arguably the most complex and less used of the three statements.

[rhettinger]

some of theses are great suggestions. I'll do an update shortly.

[ezio-melotti]

The attached patch addresses 8) -- you might want to use it as a starting point (that's what I was going to fix before deciding to do a full review of the page).

[rhettinger]

Thanks.

[elibendersky]

Ezio, your fix for 8 is definitely good. Space makes it cleaner, as well as compliant to PEP-8, which explicitly recommends to surround operators with spaces.

Note, however, that this should be applied in other places as well, not only the complex number samples. For example:

2+2
(50-5*6)/4

etc.

There's quite a bit of inconsistency in the samples. Some surround operators with spaces and some don't. I think converging on a single consistent, PEP-8 compliant convention of surrounding with spaces always throughout the tutorial is a good idea.

[elibendersky]

Comments on some of the suggestions:

1. Agreed
2. Can be combined with (3), I think. Just show the number example with the explanatory comments. They speak for themselves. No need for the SPAM and STRING assignments.
3. Yep. Can be replaced by "A value can be assigned to several variables in a single statement"
4. There's the tradeoff of rigor vs. simplicity here, since this is still a tutorial for beginners, right? What alternative would you propose?
5. Totally agree. I don't think complex numbers deserve more than a single trivial example and one sentence dedicated to them in the tutorial, if that...
6. Yes. See my previous message in this issue
7. "It differs from just writing the expression you want to write" is definitely confusing
8. Agree
9. This is kind-of mentioned later in the negative index part. It may be worth mentioning that a single index must be within bounds, but the explanation on degenerate slices has its place too, since it's a friendly feature of Python many rely on.
10. Agree
11. This is probably too arguable to be included. With Python's duck typing there *is* sometimes place for placing different objects in the same list, with the understanding that they all have some common behavior (for example, callables).
12. Agree

[merwok]

Be careful with whitespace changes. Sometimes not putting whitespace around an operator helps to see the grouping of operations, for example. The important thing is “Readability counts”, not “Always put whitespace around operators”. A huge part of understanding PEP-8 is to know when not to follow PEP-8 (PEP-20 is not called a Zen for no reason :)

About 5)-6): I really wish the docs wouldn’t use the term “variable”, which means something else in most other programming languages and always cause beginners to stumble upon unexpected-for-them binding behavior.

A remark that’s probably culture-dependent: “degenerate” nearly sounds like a racist insult to me (see 11).

[ezio-melotti]

Be careful with whitespace changes.

Here I agree with you and disagree with the PEP-8 (specifically where it says that "hypot2 = x*x + y*y" and "c = (a+b) * (a-b)" are "wrong").

In
-   >>> 3+1j*3
+   >>> 3 + 1j * 3
I intentionally added spaces around all the operators to leave the expression ambiguous.  IIUC the point of that example is to show that even if 3+1j is a single entity, normal precedence rules still apply, so I didn't want the reader to make any assumptions about the precedence based on the whitespace (or even worse thing that the whitespace might define the precedence).

Additional comments and replies about the list:

1. A user was confused about >>>, thought that was necessary to "define variables", that you had to always include it in your code. The tutorial should make clear that this is used only in the interactive interpreter and not in regular code;
   2-3) what Eli said sounds good to me;
2. "A value can be assigned to several variables simultaneously:" might lead to thing that "a = b = []" is the same as "a = []; b= []". The term "variable" has a different meaning in other languages, but that doesn't mean we should refrain to use it -- we just have to specify what we mean with "variable" (this can be done later, saying that "both a and b will refer to the same list" should be enough here);
3. here the idea is that is not the value to be assigned to the variable (like in C where the vars are like boxes and you can put values inside), but the variable that is used to refer to the object (so it's more like a label assigned to the object). Again we can don't need to be too specific here yet, but we shouldn't say wrong things either. See also http://python.net/crew/mwh/hacks/objectthink.html;
4. presenting the error raised with the index first and the fact that slices are more "permissive" later sounds better to me;
5. I'm not saying we should specifically tell users to put object of the same kind in a list, but just to avoid focusing on this aspect and use "realistic" examples. Adding a note at the end saying that "lists can also contain objects of different types" should be enough;