Style guide questions

[calebfoss]

Topic

As we're working on example revisions, I had a few questions about the code style guide.

1. Using single quotes for strings: This means that if a contributor is writing their code in the p5 editor and presses the Tidy Code button, they are breaking the style guide. This is true of any editor using Prettier. On my workspace, I customized Prettier to use single quotes so that I could still use it. Since there is no explanation included, I wanted to ask the reasoning for this rule. If we're sticking with it, I'd recommend the p5 editor's Tidy Code feature be modified to fit and perhaps instructions in the style guide on how to customize Prettier on other editors.
2. Don't use for loops for iterating over arrays: This requires us to use syntax that I think is much harder to read and less accessible for folks new to programming. I would strongly advocate for using for... of loops for arrays. I would love for creators to feel able to try out iteration without learning about arrow functions, array methods, and passing anonymous functions into methods. Otherwise, we're adding a ton of steepness to the learning curve.

Tagging @nickmcintyre and @raclim for thoughts

[limzykenneth]

1. No particular reason that single quote is chosen since there won't be any. The editor should be able to be configured to use single quote instead of double quote for tidy code. An issue can be filed there.
2. The style guide recommends .forEach and not for loops. Is what you mean here being that to use for...of instead of .forEach?

[nickmcintyre]

1. Good point. I actually made the same suggestion to match the p5.js Web Editor's style. My understanding is that Prettier was removed as a dev dependency for performance reasons. We stuck with a modified version of the Airbnb JavaScript guide, which uses single quotes. I agree we should aim for consistency.

2. I disagree about readability, but I hear your point about smoothing out the learning curve. How about we linger here for a moment? Here are some code snippets to compare different iteration scenarios:

Simple iteration

for (let mover of movers) {
  mover.update();
  mover.render();
}

movers.forEach((mover) => {
  mover.update();
  mover.render();
});

Using an index

for (let i = 0; i < movers.length; i += 1) {
  let x = i * 10;
  let y = 20 * sin(x * 0.01) + 200;
  movers[i].pos(x, y);
  movers[i].update();
  movers[i].render();
}

movers.forEach((mover, i) => {
  let x = i * 10;
  let y = 20 * sin(x * 0.01) + 200;
  mover.pos(x, y);
  mover.update();
  mover.render();
});

Updating

for (let i = 0; i < sizes.length; i += 1) {
  sizes[i] += 1;
}

sizes = sizes.map((size) => size + 1);

Everyone's learning path is different, but it's probably safe to assume that someone programming with arrays could pick up .forEach() pretty quickly. Our intro chapter will teach arrays after functions, basic OOP, and loops. .forEach() and other array methods fit pretty naturally into that scope and sequence.

All that said, it seems like @calebfoss suggested a more general principle of using syntax with the fewest prerequisites (please feel free to correct me). @katlich112358 @dkessner @MsQCompSci @limzykenneth @davepagurek @Qianqianye what do y'all think about array methods? Are there any other opportunities to simplify the the code style guide?

[limzykenneth]

The point about having the index is interesting. With a for...of loop, the index does not come directly but it is possible for the user to use arr.entries() with a full for (const [i, val] of arr.entries()) although in this case the user will need to know about .entries() and array desctructuring for [i, val] which it is worth thinking about how it compares with .forEach((val, i) => {}).

On the other hand, for...of have a couple possible advantages over .forEach in that 1. you can break or continue; 2. await will work as expected.

[davepagurek]

I don't have a super strong opinion on this one, both .forEach or for..of have their advantages and I'm happy to use either in examples.

One minor bit to add to the discussion: I'm not sure about everyone else, but even though I know the difference between for..in and for..of, I find it harder sometimes to spot one vs the other when reading code, as both read very similarly in English. I'm not sure if we have any examples that loop over both object keys and arrays, but in that case, Object.keys(array).forEach(...) is more verbose but maybe clearer to show that something different is happening.

[calebfoss]

Thank you for the discussion! I appreciate y'all taking the time.

I wanted to clarify a couple things. I personally really like using array methods and find them quite readable if written well, but speaking as an instructor these are the aspects of using array method that would present obstacles for my students:

1. => - This is the first time students would see this symbol. Previously I have not taught lambda expressions / arrow functions at all, so it would be the only place they would encounter it. In the p5 Examples, iterating over arrays would be the only place they would be used.
2. implicit return value - By the time my students would be iterating over arrays, they would have gotten started with writing their own functions, but they would only be using them to draw custom shapes. So they would not only need to learn about returning values from custom functions but also the way the arrow functions can implicitly return values.
3. passing a function into a function - I've found this is tough for beginners to conceptualize, especially since even those with experience in other languages may not have dealt with this. That being said, they would also deal with this in p5.Element event methods like mousePressed.

My students would have already learned about for loops, so that syntax structure would be familiar. Honestly, if the p5 code examples use array methods, as an instructor, I would most likely show my students a modified version that uses the tools they've already learned.

I wrote a little add-on with a Python-esque range function to help students with numerical iteration. It could also be used for updating array values, since for... of doesn't allow for that:

for(let index of range(sizes.length)) {
    sizes[index] += 1;
}

I was thinking about proposing that function for the base p5 library, but I'll put that in a new thread. A big benefit is that infinite loops are impossible, which is a huge plus for beginners.

@davepagurek Good point about the "in" vs "of" confusion. That is a notable downside.

@limzykenneth Good point about break, continue, and await. One annoying thing about iterating over the entries method is that the indices are strings. It's not a huge issue, but something that caught me off guard that I wanted to mention.

Hearing the pros and cons for different options makes me wonder - maybe the style guide could include multiple and suggest different ways of iterating for different situations? Using only array methods would be more consistent, and if we're sticking with that, I'll make sure all the relevant examples use them. Again, I would just work around that when I'm teaching.

[davepagurek]

One annoying thing about iterating over the entries method is that the indices are strings

I just did a quick test, it looks like they're numbers here at least?

Iterating over the indices of an array with in definitely makes strings though:

[calebfoss]

One annoying thing about iterating over the entries method is that the indices are strings

I just did a quick test, it looks like they're numbers here at least?

Iterating over the indices of an array with in definitely makes strings though:

Oops! Thanks for checking.

[calebfoss]

Also just to contradict myself a bit and confuse things - the same thing I said about => being a new symbol would be true about the keyword "of". My opinion is that using "of" is much simpler to learn, and the syntax involved is much simpler. As an English speaker, though, I'm biased towards English keywords over abstract symbols.

[calebfoss]

A more verbose approach that would avoid arrow functions would be:

function addOne(size, index) {
  sizes[index] = size + 1;
}

sizes.forEach(addOne);

[limzykenneth]

function addOne(size, index) {
  sizes[index] = size + 1;
}

sizes.forEach(addOne);

Just a quick note that this style is also what I see Dan Shiffman do in the beginner oriented videos for Coding Train, albeit for event handlers, so it's not out of the question.

[calebfoss]

function addOne(size, index) {
  sizes[index] = size + 1;
}

sizes.forEach(addOne);

Since it doesn't look like this goes against the style guide as-is, I'm thinking this would be a good format to use in the examples. We have already examples with named functions being passed into DOM element event methods, so this would be more familiar. If anyone sees any issues with that, please let me know. If not, it might be worth including this style in the style guide as an alternative.

[davepagurek]

I think this is OK as long as we keep the function and its use side-by-side like in these snippets so that people can still read the code linearly without jumping around too much, as opposed to placing them next to globals like draw.

[limzykenneth]

For me it is still a bit hard to decide which to go for. In everyday coding I instinctively use .forEach with inline closure just because I personally like the syntax but when later I found out I need to await, I'll be converting it into for...of. I don't know really is the main takeaway.

One thing to note also is that we might do some edits to the style guide later on to clarify differences between example code and p5.js source code style, ie. example code style are designed to be consistent, simple, and beginner friendly; while the p5.js source code style may have more in the ways of case by case analysis, small tricks, and optimizations when necessary. One example is const and let, example code only uses let while p5.js source code uses const whenever possible and only use `let if reassignment is needed.

Forgot to add,

sizes.forEach(function(size){
  size = size + 1;
});

is also possible if the desire is to avoid arrow syntax, as long as this loop is not used in object methods.