Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change variable name from 'char' to 'letter' #569

Open
wants to merge 4 commits into
base: gh-pages
from

Conversation

@donnaaboise
Copy link

@donnaaboise donnaaboise commented Jul 18, 2018

I propose changing the variable name used to introduce Python loops from 'char' to 'letter'. The concern is possible confusion with the use of char in compiled languages.

_episodes/02-loop.md Outdated Show resolved Hide resolved
@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 18, 2018

Thanks @donnaaboise. This change would also require updating the related figure.

@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Jul 18, 2018

I have looked around in the files that generate this lesson, and don't see how to change the figure. What am I missing?

@annefou
Copy link
Contributor

@annefou annefou commented Jul 18, 2018

You are right. The figure loops_image.png is located in the fig directory but I can't find its corresponding svg file.

@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Jul 18, 2018

Good - so at least I was looking in the right place.

@@ -158,8 +158,8 @@ of the loop body (e.g. `end for`); what is indented after the `for` statement be
> ## What's in a name?
>
>
> In the example above, the loop variable was given the name `letter` as a mnemonic;
> We can choose any name we want for variables. We might just as easily have chosen the name
> In the example above, the loop variable was given the name `letter` as a descriptive variable chosen to make the code easily understandable. However,

This comment has been minimized.

@maxim-belkin

maxim-belkin Jul 18, 2018
Contributor

I suggest:

In the example above, the loop variable was given a descriptive name letter, making it really easy to understand the code. However, we might just as easily have chosen any other name, such as char, c, or even banana as long as we use the same name inside the loop:

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 18, 2018

Nice! Thanks for finding this, @ldko.

@donnaaboise, this is how to get this figure back to your local repo:

git checkout af0e017^1 fig/loops_image.svg
@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Jul 18, 2018

I checked out the SVG file, but really don't have any idea how to edit it. Just viewing it as a text file (after tidying it up), there is no place where I can obviously change 'char' to 'letter'. I didn't make much progress in Inkscape either. I pushed the SVG file to the repo (the untidy version - I can also push a tidy version, if that helps). Can someone let me know how to edit this file? Or maybe make the few minor changes? Thanks.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 18, 2018

I will take care of the figure.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 24, 2018

Prepared two versions (don't mind the lack of spaces in front of print(letter) in one of them - I will fix this later).

The first one is just an updated version of the "old" figure.

In the new one I tried to improve the explanation: variable letter is a messenger/mediator between word and print function.

1. Updated figure

loops_image-new-plain

2. New version

loops_image-new-version

Please share your thoughts and ideas how to improve the figures.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 24, 2018

Forgot to mention: please comment on all aspects of figures: font, font size, colors, line widths, (missing) arrowheads, rounded corners of rectangles, etc.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 2, 2018

What we can change in the 'new version' of the figure: we can move the line from letter to print(letter) to connect the two letters, rather than the middle points of two rectangles. Then, we can move the line that comes out of print(letter) to start under print to emphasize the point that it is print that prints things to the screen.

@maxim-belkin maxim-belkin self-assigned this Aug 2, 2018
@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Aug 3, 2018

I'll admit that I am not fan of either of these figures, and wonder if they are even necessary. Of course, they are very nicely done, but I think they may be more confusing than helpful. For example, it might not be obvious to a beginner what the numbers mean, since no numbers are printed by the actual code, and there is no reference to an index in the code.

I wonder if a second code fragment would be helpful :

for i in range(len(word)):
    letter = word[i]
    print([i,letter])

This could precede the example without the indexing and might help to make the figures more clearly understood. Then the second (original) code could be presented as the "python" way of writing the loop.

I also appreciate just presenting the original code. It is certainly cleaner. If the lesson emphasizes that the letters will be printed in order (this might not be obvious from the more Pythonic code), the figures might be more easily understood.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

This PR changes lines 100 -- 160.
len is first mentioned on line 240. Range is mentioned on lines ~260.
Lists (in the current version of the lesson) are mentioned in the next episode.

I'm OK with dropping the figure altogether as I'm not a big fan of it either but visuals usually help understand concepts. We just have to make a good visual if we're to keep it.

@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Aug 3, 2018

Okay - then there does need to be a way to indicate that the letters are printed in order, and a figure could certainly help. I think about what can be done to tweak the current figure. For example, do we need the numbers (indices)?

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

For example, do we need the numbers (indices)?

I remember they caused some confusion at at least one workshop that I taught, so no, we don't necessarily need them.

We could show something like the graphics below: a horizontal strip with 6 sections and in each section we show the word 'oxygen' with a small vertical arrow pointing at one of the letters, then some clarifying text (letter = o) and then the corresponding output on the screen.

↓                 ↓                ↓                ↓                ↓                ↓
o x y g e n     o x y g e n    o x y g e n    o x y g e n    o x y g e n    o x y g e n

letter = 'o'    letter = 'x'   letter = 'y'   letter = 'g'   letter = 'e'   letter = 'n'

o               o              o              o              o              o
                x              x              x              x              x
                               y              y              y              y
                                              g              g              g
                                                             e              e
                                                                            n
@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Aug 3, 2018

This looks great!

The thing that a figure can't quite capture is the dynamic nature of the loop and the idea that the code is called several times, one iteration at at time. So I wonder if adding something like :

'first pass through loop', 'second pass through loop' and so on

above each of your 6 figures would help with this.

In some sense, the very first code fragment, which prints word[0], word[1], word[2] and so on illustrates this idea best. So it is tempting to just use this fragment :

for i in [0,1,2,3,4,5]:
    letter = word[i]
    print(letter)

But if they haven't seen lists, this could be confusing.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

I like your suggestion to add explanatory text. I like the for loop too (it would be easy to explain) but, as you understand, we can't do that until we swap the order of episodes.

@abostroem
Copy link
Contributor

@abostroem abostroem commented Aug 3, 2018

Apologies for being late to the conversation. I have found that people transitioning from an index based language to an object oriented language often struggle with the idea of looping over objects (and not indices). I want to raise the concern that this example could enhance that confusion and is no demonstrating the loop idea of for object in list... .

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

@abostroem, do you mean this example (for letter in word) or the figure/image?

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

or what I proposed here

@abostroem
Copy link
Contributor

@abostroem abostroem commented Aug 3, 2018

The figure looks great!
My concern is about the code fragment and changing it from:
for letter in word:
to
for i in [0, 1, ...]: or for i in range(len(word)):

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

What if we delete the current figure (line 146 in the episode and the PNG file) in this PR and save its SVG version for the future... It looks like we again arrive at the necessity to talk about Python lists before Python for loops and this change (even though I already started it) might take some time.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Aug 3, 2018

Also, for our own reference this figure was added in 9c8b5f4

@donnaaboise
Copy link
Author

@donnaaboise donnaaboise commented Aug 3, 2018

One big difference between index-based languages (C, Fortran) and object languages (Python, Matlab) is that in both Python and Matlab, the loop variable takes iterates through items in a list or array. Whether the code is

% Matlab
for i = [0,1,2,3,4,5]
    disp(i)
end

or the equivalent Python code, or the letter code, the loop iterates over values in a list. I would think that a simple introduction to this concept could be useful, even if a more complete discussion of lists were saved for a following episode.

@maxim-belkin maxim-belkin force-pushed the swcarpentry:gh-pages branch from 4753644 to 90848ea Oct 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.