Rework `javascript-101/arrays.md` #88

Merged
merged 4 commits into from Apr 9, 2012

Projects

None yet

5 participants

@ddprrt
Contributor
ddprrt commented Mar 16, 2012

Did a complete rework of the Array section (for starters, just to get used to the environment). And tried to explain each Array method.

@ajpiano
Member
ajpiano commented Mar 16, 2012

Awesome! You picked a great thing to just acclimate yourself, and this is a healthy improvement. This isn't documented anywhere yet, so you couldn't 'have possibly known to do it, but can you adjust the YAML to the following format:

attribution:  
- jQuery Fundamentals
- Stefan Baumgartner
github: ddprrt

The 'github' param controls, right now, whose avatar shows up on the article, which your contribution certainly merits already. I'll also leave some additional edits as line notes. Thanks for jumping in and helping out!

@ajpiano ajpiano commented on an outdated diff Mar 16, 2012
content/javascript-101/arrays.md
---
Arrays are zero-indexed lists of values. They are a handy way to store a set of
related items of the same type (such as strings), though in reality, an array
-can include multiple types of items, including other arrays.
+can include multiple types of items, including other arrays. Arrays in Javascript
+work bascially like in most other programming or scripting languages, although there
+are some subtle differences.
+
+To create an array you can either use the object constructor or the literal declaration,
+by assign your variable a list of values right after the declaration.
@ajpiano
ajpiano Mar 16, 2012 Member

assigning, not assign

@ajpiano
ajpiano Mar 16, 2012 Member

We should really slam home the fact that the literal is strongly preferred

@ajpiano ajpiano commented on an outdated diff Mar 16, 2012
content/javascript-101/arrays.md
@@ -2,38 +2,195 @@
chapter : js101
section: 6
title: Arrays
-attribution: jQuery Fundamentals
+attribution: jQuery Fundamentals, Stefan Baumgartner (@ddprrt)
---
Arrays are zero-indexed lists of values. They are a handy way to store a set of
@ajpiano
ajpiano Mar 16, 2012 Member

Let's make this "zero-indexed, ordered lists"

@ajpiano ajpiano commented on an outdated diff Mar 16, 2012
content/javascript-101/arrays.md
<javascript caption="A simple array">
-var myArray = [ 'hello', 'world' ];
+var myArray1 = new Array( 'hello', 'world' ); // with constructor
+var myArray2 = [ 'hello', 'world' ]; // literal declaration, the prefered way
@ajpiano
ajpiano Mar 16, 2012 Member

preferred, not prefered

@ajpiano ajpiano commented on an outdated diff Mar 16, 2012
content/javascript-101/arrays.md
<javascript caption="A simple array">
-var myArray = [ 'hello', 'world' ];
+var myArray1 = new Array( 'hello', 'world' ); // with constructor
+var myArray2 = [ 'hello', 'world' ]; // literal declaration, the prefered way
+</javascript>
+
+If you don't know your values yet, it is also possible to declare an empty Array, and
+add elements either through functions or through accessing by index:
+
+<javascript caption="Creating empty arrays and adding values">
+var myArray = []; // var myArray = new Array(); would also work
@ajpiano
ajpiano Mar 16, 2012 Member

don't need the comment here!

@ajpiano
Member
ajpiano commented Mar 16, 2012

Food for thought....
Would be nice to cover some "applied" array content. Using arrays as queues, using arrays as a necessity because you have data that needs to be ordered (as opposed to in an object). Mapping collections to produce new arrays (very relevant to solving all sorts common tasks). The fact that jQuery objects are array-like. A lot could go in here - should it be in this article, or separated out?

@ajpiano ajpiano and 2 others commented on an outdated diff Mar 16, 2012
content/javascript-101/arrays.md
---
Arrays are zero-indexed lists of values. They are a handy way to store a set of
related items of the same type (such as strings), though in reality, an array
-can include multiple types of items, including other arrays.
+can include multiple types of items, including other arrays. Arrays in Javascript
+work bascially like in most other programming or scripting languages, although there
+are some subtle differences.
@ajpiano
ajpiano Mar 16, 2012 Member

I'm not sure this sentence is necessary, unless we actually plan to explain the subtle differences that exist at some point in the article.

@ddprrt
ddprrt Mar 21, 2012 Contributor

Agreed. My first attempt on writing this article was more on focussing on the differences for programmers who didn't get in contact with JS yet, but then I thought I might miss the point

@mikesherov
mikesherov Mar 25, 2012 Member

bascially => basically

@ddprrt
Contributor
ddprrt commented Mar 21, 2012

Wow! Thanks for the quick answer! I thought that the Arrays article might me a good starting point, for me and a rework of the JavaScript 101 section in general. I share your point in expanding with "applied" examples, but I'm not quite sure if we should mix in jQuery examples at that point, but focussing on a seperate "Arrays and jQuery" chapter later on. I don't know if the jQuery object is discussed in a later chapter, but I'm all for explaining it as much in-depth as possible. jQuery is a mighty tool, but can be so mis-used if you don't know what's inside. Since this is a learning documentation, we should keep in mind that alot of complete JS/Web development beginners will go for that.

@addyosmani
Member

Hey @ddprrt. Really great work on this so far!

In my opinion, we perhaps shouldn't be mixing in jQuery examples with the JS101 section (just yet).

The fact that jQuery objects are array-like. A lot could go in here - should it be in this article, or separated out?

I think separated out makes the most sense here. Ideally we don't want to confuse people who are looking at anything to do with jQuery for the first time when teaching them JS fundamentals.

Would it be overkill for us to also make a reference to forEach() in this section? Chrome, Firefox, IE9, Safari and Opera support ES5's native array.forEach, but if we're trying to just teach the baseline that'll work in older browsers too that's understandable.

There's also an argument for including `for( x in y)``, but we can do whatever you guys feel avoids confusion.

@ddprrt if you could check your changes against latest that would be great. At present this PR can't be automatically merged in (even though I know there's still work to be done on it) :)

@ajpiano
Member
ajpiano commented Mar 25, 2012

+1 for explanation of .forEach

@connor
Contributor
connor commented Mar 28, 2012

+1 for native .forEach

@ddprrt
Contributor
ddprrt commented Mar 29, 2012

Hello everyone!

I added for...in and forEach to the article. For now I left out "applied" array examples, mostly because I didn't come up with an example that hasn't either jQuery content or some kind of pattern in it (was thinking about animation queues filled up on user interaction).

@addyosmani Hope I did everything right, should by now up to date with upstream :-)

I think separated out makes the most sense here. Ideally we don't want to confuse people who are looking at anything to do with jQuery for the first time when teaching them JS fundamentals.

Totally agree

@addyosmani

This looks good. If we can make a specific reference to ES5 (https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/forEach) just so developers are clear what version of ES/JS is needed for support that would also be helpful. As you'll see in http://kangax.github.com/es5-compat-table/, Opera and Safari also support forEach now. Perhaps including the lowest version number with support would help?

@addyosmani

Thanks for this!. It looks good. I've just made a comment that you might like to address, but we could probably go for a merge if there is nothing else outstanding.

@ajpiano
Member
ajpiano commented Apr 9, 2012

Merging now! Thanks. In the future please do not commit directly to master, thanks! :)

@ajpiano ajpiano merged commit 3823698 into jquery:master Apr 9, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment