Merge pull request BonsaiDen#243 from matthewgertner/master

Added details about using hasOwnProperty in ES5

Author: timruffles

doc/en/object/forinloop.md

@@ -3,10 +3,10 @@
 Just like the `in` operator, the `for in` loop traverses the prototype
 chain when iterating over the properties of an object.
 
-> **Note:** The `for in` loop will **not** iterate over any properties that 
-> have their `enumerable` attribute set to `false`; for example, the `length` 
+> **Note:** The `for in` loop will **not** iterate over any properties that
+> have their `enumerable` attribute set to `false`; for example, the `length`
 > property of an array.
-    
+
     // Poisoning Object.prototype
     Object.prototype.bar = 1;
 
@@ -16,9 +16,18 @@ chain when iterating over the properties of an object.
     }
 
 Since it is not possible to change the behavior of the `for in` loop itself, it
-is necessary to filter out the unwanted properties inside the loop body; 
-this is done using the [`hasOwnProperty`](#object.hasownproperty) method of 
-`Object.prototype`.
+is necessary to filter out the unwanted properties inside the loop body. In
+ECMAScript 3 and older, this is done using the [`hasOwnProperty`](#object.hasownproperty)
+method of `Object.prototype`.
+
+Since ECMAScript 5, `Object.defineProperty` can be used with
+`enumerable` set to `false` to add properties to objects (including `Object`)
+without these properties being enumerated. In this case it is reasonable
+to assume in application code that any enumerable properties have been added
+for a reason and to omit `hasOwnProperty`, since it makes code more verbose and less
+readable. In library code `hasOwnProperty` should still be used since
+assumptions cannot be made about which enumerable properties might reside
+on the prototype chain.
 
 > **Note:** Since `for in` always traverses the complete prototype chain, it
 > will get slower with each additional layer of inheritance added to an object.
@@ -32,20 +41,26 @@ this is done using the [`hasOwnProperty`](#object.hasownproperty) method of
         }
     }
 
-This version is the only correct one to use. Due to the use of `hasOwnProperty`, it
-will **only** print out `moo`. When `hasOwnProperty` is left out, the code is 
-prone to errors in cases where the native prototypes - e.g. `Object.prototype` - 
+This version is the only correct one to use with older versions of ECMAScript.
+Due to the use of `hasOwnProperty`, it will **only** print out `moo`.
+When `hasOwnProperty` is left out, the code is prone to errors in cases where
+the native prototypes - e.g. `Object.prototype` -
 have been extended.
 
-One widely used framework that extends `Object.prototype` is [Prototype][1].
+In newer versions of ECMAScript, non-enumerable properties can be defined with
+`Object.defineProperty`, reducing the risk of iterating over properties without
+using `hasOwnProperty`. Nonetheless, care must be taken when using older
+libraries like [Prototype][1], which does not yet take advantage of new ECMAScript features.
 When this framework is included, `for in` loops that do not use
 `hasOwnProperty` are guaranteed to break.
 
 ### In Conclusion
 
-It is recommended to **always** use `hasOwnProperty`. Assumptions should never
-be made about the environment the code is running in, or whether the native
-prototypes have been extended or not.
+It is recommended to **always** use `hasOwnProperty` in ECMAScript 3 or lower, as well as
+in library code. Assumptions should never be made in these environments about whether
+the native prototypes have been extended or not. Since ECMAScript 5, `Object.defineProperty`
+makes it possible to define non-enumerable properties and to omit `hasOwnProperty` in
+application code.
 
 [1]: http://www.prototypejs.org/
 

doc/en/object/hasownproperty.md

@@ -21,10 +21,10 @@ does **not** traverse the prototype chain.
     foo.hasOwnProperty('bar'); // false
     foo.hasOwnProperty('goo'); // true
 
-Only `hasOwnProperty` will give the correct and expected result; this is
-essential when iterating over the properties of any object. There is **no** other
-way to exclude properties that are not defined on the object itself, but
-somewhere on its prototype chain.
+Only `hasOwnProperty` will give the correct and expected result. See the section
+on [`for in` loops](#object.forinloop) for more details on when to use
+`hasOwnProperty` when iterating over object
+properties.
 
 ### `hasOwnProperty` as a Property
 
@@ -53,6 +53,6 @@ necessary to use an *external* `hasOwnProperty` to get correct results.
 
 Using `hasOwnProperty` is the **only** reliable method to check for the
 existence of a property on an object. It is recommended that `hasOwnProperty`
-is used in **every** [`for in` loop](#object.forinloop) to avoid errors from
-extended native [prototypes](#object.prototype).
+be used in many cases when iterating over object properties as described
+in the section on [`for in` loops](#object.forinloop).