Unit 4 lesson 2 contrived examples considered harmful.

[jdonwells]

There are two problems with contrived examples. The first is code that the students can't understand because it simply makes no sense. The second is most of these contrived examples are badly written Python. We want to show the students well written Python only.

I would even go so far as to say if you can't think of a well written Python example maybe you should skip what you want to show them entirely. Showing the students how to traverse a list using for i in range(0, len(list)) is probably not something to show them at all. There are no good examples because no one would do that.

In Unit 4 lesson 2 we show them this code:

for i in range(len(numbers)):
    numbers[i] = numbers[i] * 2

The correct way to do that is this:

doubled_numbers = [n * 2 for n in numbers]

We also show them this code:

def is_reverse(word1, word2):
    if len(word1) != len(word2):
        return False
    i = 0
    j = len(word2)
    while j > 0:
        if word1[i] != word2[j]:
            return False
        i = i + 1
        j = j - 1
    return True
print(is_reverse('pots', 'stop'))

The correct way to do that is this:

def is_reverse(word_a, word_b):
    return word_a == word_b[::-1]


print(is_reverse('pots', 'stop'))

Here are my new examples. I am going to show 4. One each for the major traversals (map, filter, reduce) and one for using range.

Traversing a list to transform it. (map)

def strings(list):
    all_strings = []
    for item in list:
        all_strings.append(str(item))
    return all_strings

Traversing a list to summarize the items. (reduce)

def sum(numbers):
    """Return a total of the numbers"""
    total = 0
    for number in numbers:
        total = total + number
    return total

Using a traversal to filter a list. (filter)

def only_primes(numbers):
    """Return a list of the primes in the numbers list"""
    primes = []
    for n in numbers:
        if is_prime(n):
            primes.append(n)
    return primes

Using range() to generate a list for traversal.

def is_prime(n):
    for divisor in range(2, n):
        if n % divisor == 0:
            return False
    return True

[dvgrn]

Well... this post might open up some interesting philosophical discussions.

I'm not sure anyone is playing the part of high-level architect for this course, who could give an official ruling on whether all of these replacements are a good idea or not. But on a first reading -- and without reading through the entire set of lessons up to Unit 4 again -- I'd be fairly worried that showing these technically "correct" ways of doing things at this point in the course would be more confusing than helpful.

I taught from the 2nd-semester course material last year, and as I went along I tried to repair the things that really made no sense at all, or absolutely didn't work. (There were quite a few broken code snippets in the PowerPoint presentations, but not nearly as many in the HTML notes.) But I was very careful not to touch code like the above examples that was written in a sub-optimal way, since it was often written that way very deliberately -- because the key concepts that would allow a rewrite hadn't been introduced yet.

In other words, some of these examples don't look like "badly written Python" to me -- they're just "Python written with reduced syntax options".

The course design, as far as I understood it -- it made a little more sense once I'd gotten through the whole thing -- was to be very careful to avoid throwing too much syntax at students all at once. There was even a point where Booleans were introduced before "if" statements... not sure how successful that particular decision was, but it was deliberately done and it made for a consistent step-by-step flow through the concepts.

So I really don't have any quarrel with

for i in range(0, len(word_list)):

at this point in the course -- because that's the only syntax for the "for" command that they've been introduced to up to this point. At least in my experience, while it would be easy to show students a code example like

return [pluralize(fruit) for fruit in fruits]

and say that that's "the correct way", it would then be really painful to get students to generate new code similar to that as an answer to a homework assignment. It doesn't line up with what they've experienced so far, either in Snap! or in previous units' use of for loops. So they would put in parentheses instead of square brackets, or try to put the "for" keyword first, or try to call pluralize() first and then return the results -- and when you're done explaining all those "mistakes", they won't necessarily understand why "the correct way" works. If you instead break down the problem and solve it using the tools that the course has provided to students so far, you get something along the lines of the lab solution.

Also, if the lab spec says that the function is supposed to modify the list of words, then returning a new list is not a solution at all, because it doesn't follow the spec. I actually think it's much more important to emphasize that solutions should precisely match the spec, than to emphasize using "correct Python" no matter what. It's certainly possible to change the spec along with the solution -- but my sense is that if you really want students to be able to use list comprehensions to solve Unit 4 labs, you will really have to rewrite the whole course.

Somewhat similarly,

return word_a == word_b[::-1]

might be acceptable if that specific slice syntax has been covered thoroughly back in Unit 2, so that students can look at "[::-1]" and recognize immediately that that means "reverse word_b". I don't recall that Unit 2 got quite that far with slice syntax -- this is only an introductory course, and there just isn't time to give students a thorough grounding in every possible syntax detail.

I think the key idea of the course's current design is that after students have gone through the effort of writing some working code using limited-syntax Python, they'll be much more prepared to understand and appreciate the "syntactic sugar" available from list comprehensions, advanced slicing, and so on.

[jdonwells]

I think the most important sentence in the original post is this one: "I would even go so far as to say if you can't think of a well written Python example maybe you should skip what you want to show them entirely." In the above examples my goal is to show how far off the given code is from reality. It should be clear that we need to not show that code. My point is not to rewrite but rather unwrite. Choose a different example that isn't contrived and actually should be solved that way.

I do not advocate pulling material ahead. I have opened more than a few bugs for exactly that. I have also proposed shuffling the Unit projects for that reason. #349 Lesson 2.06 on game loops prior to Unit 4 Loops seems to be a product of pull ahead.

In terms of exercises, if an exercise says "modify the list in a function" change the exercise. That just doesn't do anyone any good.

[dvgrn]

Thanks! That certainly makes the intent clearer.

You mentioned this code as being harmful to show:

for i in range(len(numbers)): numbers[i] = numbers[i] * 2

I'm not sure I'd agree that in an introductory course that code is so terribly objectionable. It's valid code, it's understandable, and it has the effect of doubling the values in the numbers[] list. There's something that can be learned there, about how to break down a task into steps that a computer can understand, use a for loop to set an index value to a series of integers, and do an assignment operation on each list item using that array index.

Students can usefully walk through a lot of simple examples like this to get familiar with those concepts. It doesn't seem necessary to worry whether an example is contrived, or whether there's some other "correct" way to do it, before they even know what all the syntax options are. Last year I did what I could to give students a clear understanding of which syntax or approach might be better in which circumstance, but honestly a lot of that level of detail is simply beyond the scope of this course.

doubled_numbers = [n * 2 for n in numbers]

creates a whole new array, using twice as much memory, and doesn't change the values in the numbers[] array. Ultimately that doesn't seem any less contrived than the original code -- we could just write numbers[k]*2 instead of doubled_numbers[k] wherever we would otherwise use this silly new array. In an intro course there are inevitably going to be a lot of "toy" examples, and it really seems like that should be okay sometimes.

Re: "There are no good examples because no one would do that":

It seems to me there are cases where it makes reasonably good sense to iterate through a list inside a function, and make changes to items in the list. An example might be inspecting items for some kind of error condition, and repairing any problems that are found: you wouldn't expect to be changing every item in the list, but you might change a few. That could end up being more efficient than making a whole new copy of the list inside the function and returning the copy. No doubt there are better ways -- but are there better ways that only include code that's readily understandable for someone with mostly just a background in Snap?

In any case, efficiency isn't really an issue in a lot of Python code, but readability and maintainability can be very important -- and "readability" can mean something very different for students (and teachers!) who are just getting started.

Long story short, if the above were a bug filed against that code example, I really wouldn't know exactly what I could do to make an improvement. If we can't use list comprehensions yet (this intro course doesn't get into them at all, does it?) then what can we do instead that is as conceptually simple as iterating through a list and updating it in place?

[jdonwells]

The example in question could be specified by saying I want a list of numbers divisible by 1, 2, and itself. I could first generate a list of primes.

The reason I would never show a student changing a list inside a function is that the existence of that function means there also exists a variable who's value is one thing in part of the program and another thing in another part. It depends on when and if that function gets called. A variable with two definitions isn't something you ever want to do.

Even at this level I would avoid encouraging it by showing it. It becomes a bad habit to be broken later.

I updated the original post with my new examples. I feel this is the correct way to go. I am also giving names to the 3 main types of traversals.

With this in the lesson I am expecting the lab to look like this:

def fruit_pluralizer(fruits):
    """fruits is a list of names that will be made
    plural and returned as a list."""
    plurals = []
    for fruit in fruits:
        plurals.append(pluralize(fruit))
    return plurals


def pluralize(word):
    if (word[-1] == 'y'):
        return word[0:-1] + 'ies'
    return word + 's'


print(fruit_pluralizer(['banana', 'raspberry', 'apple', 'blueberry']))

I can live with that.

[dvgrn]

First, I'd like to say that I remember trying to "teach past" some very contrived examples in the 2nd-semester-Python lecture material -- having to say things like "you wouldn't ever do this in real code, but what will Python do when you run this program?" I don't want to come across as defending the existing code snippets: there absolutely are many improvements that could be made.

I'm just not finding it nearly as clear as you are, that the first example you quoted will teach any bad habits, or that it's in need of replacement. This unit isn't telling students "here's the best way to double a list of integers" or "here's the best way in Python to check if one word is the reverse of another word". It's exercising loops in different ways to accomplish various goals. Seems like at this stage we need goals that are simple and can be clearly stated, more than we need real-world-looking goals.

-- That said, the second code snippet is very very weird, because it's in a lesson called "For loops", but it doesn't contain any for loops -- it just has a very awkward for-loop substitute. Something like this might make more sense, with only one deliberate error (in the line with the comment) instead of two:

def is_reverse(word1, word2):
    wordlength=len(word1)
    if wordlength != len(word2):
        return False
    for i in range(wordlength):
        j = wordlength - i  # index of letter opposite the (i)th letter
        if word1[i] != word2[j]:  
            return False
    return True
print(is_reverse('pots', 'stop'))

Yes, this is still not the best way to define is_reverse(), but it's a decent example of the use of a for loop to iterate through a string and refer to individual letters by their index values -- and, in this case, to break out of the loop as soon as a discrepancy is found. If students can find the error in this code, they're not just picking up bad habits, they're getting some useful practice with debugging for loops.

-- Or the lesson could start with the original code, I suppose, and then show how to rewrite it using a for loop. But there's only so much time in a class session. The original code might fit better in a unit called "Debugging", where students look at the values of the i and j variables and figure out what the difference is between the intended purpose of the code and its actual behavior.

> A variable with two definitions isn't something you ever want to do.

That's not exactly what's going on here, though. At least ... I think I recognize your statement as a good common-sense programming rule, but it's more like "don't use the same variable name for two different purposes". That first code snippet is just maintaining the contents of a list. If you want a program to get anything useful done, you have to change the contents of variables sometimes. Lists are an especially tricky case, since they very often have dynamic contents -- they're supposed to change as the program runs.

It would certainly be a bad idea to change the variable "numbers" to contain an integer or a string or whatever, but it's not necessarily bad form to update some values in an existing list. That doesn't necessarily cause any more confusion than

match=False
if somecondition=True:
  match=True

where "match" is a variable whose value may be different in different parts of the program...

-- Yikes, the Text Monster project was way back in Unit 2! I'm curious: what did you think of the starter code for that project? Defining the three separate floors in different variables, and having the starter code switch back and forth between them by defining a "floor" variable to point to one of those three variables, seemed like an awkward choice. It wasn't clear to a lot of my students that making changes to the "floor" variable would permanently update the "floor0", "floor1", or "floor2" lists.

Still, the way that Text Monster functions update the contents of those lists whenever something changes in the game, doesn't seem conceptually any different from code that doubles the contents of a "numbers" list in-place.

[jdonwells]

I think I didn't explain that idea well. In your example match means the same thing. Let's say you have a text monster game and on one floor match is True if you have a match to light your lantern. On another floor match is used to tell if you won your boxing match with a goblin. The difference isn't in which boolean it holds, but rather the meaning. Doubling all the numbers is a transformation of that list into something else. It needs a different name because it isn't the same list anymore.

I disagree with your statement "a decent example of the use of a for loop to iterate through a string". I am planning on skipping that slide as there is no reason to debug it because it shouldn't even exist.

(I am moving Zork to Unit 6.) Changing what is in a room doesn't change the meaning of the variable. It is still the room contents. I suppose that is an exception that I don't mind because the side affect can be clearly labeled in the function name and is expected.

The Principle of Least Astonishment may apply here.

Here is my version of the slide show. https://docs.google.com/presentation/d/1z4Z__2BsOlwLVtnZQHf379zJ_K2VYl-C_DRYZVIo-xc/edit?usp=sharing

[jdonwells]

I ended up replacing 4.04 with list comprehensions as described here #370 List comprehensions are important.