Proofread articles.

kaycebasques · kaycebasques · commit 5e0b5ffb2dae · 2014-11-02T16:53:24.000-08:00
diff --git a/docs/correctness/.init_method_is_a_generator.rst.swp b/docs/correctness/.init_method_is_a_generator.rst.swp
diff --git a/docs/correctness/access_to_a_protected_member.rst b/docs/correctness/access_to_a_protected_member.rst
@@ -37,7 +37,7 @@ Solutions
 Use ``property`` to access the member
 .....................................
 
-For new-style classes (classes that derive from ``object``, e.g. ``class Rectangle(object):``) the Pythonic way to access members is to use the built-in Python function ``property()``.
+For new-style classes (classes that derive from ``object``, e.g. ``class Rectangle(object)``) the Pythonic way to access members is to use the built-in Python function ``property()``.
 
 .. code:: python
 
@@ -66,7 +66,7 @@ For new-style classes (classes that derive from ``object``, e.g. ``class Rectang
 Add protected member to ``__all__``
 ...................................
 
-If the author of the class decides that it is accessible to directly access the protected member, he can add the protected member to the module's ``__all__`` class to indicate this. The code will execute either way, but this at least explicitly documents that it is acceptable to directly access the member.
+If the author of the class decides that it is acceptable to directly access the protected member, he can add the protected member to the module's ``__all__`` class to indicate this. The code will execute either way, but this at least explicitly documents that it is acceptable to directly access the member.
 
 .. code:: python
 
diff --git a/docs/correctness/an_attribute_hides_this_method.rst b/docs/correctness/an_attribute_hides_this_method.rst
@@ -4,12 +4,12 @@ An attribute hides this method
 Summary
 -------
 
-An attribute and a method of a class share the same name. Give the two objects unique names or else Python will raise a ``TypeError: object is not callable`` error at runtime. Python raises the error because the name is associated to the attribute, so when you insert parentheses after the name, Python actually tries to call the attribute although you were trying to call the function.
+An attribute and a method of a class share the same name. Give unique names to the two objects or else Python will raise a ``TypeError: object is not callable`` error at runtime. Python raises the error because the name is associated to the attribute, so when you insert parentheses after the name, Python actually tries to call the attribute (although you were trying to call the function).
 
 Description
 -----------
 
-When an attribute and a method have the same name, Python gives the attribute precedence. Because two objects cannot have the same name while residing in the same namespace, the method will effectively be hidden. If you try to call the method, Python will actually attempt to call the attribute, and a ``TypeError`` runtime error will occur and the module will not successfully execute. Therefore when you encounter this error you must modify the attribute and method to have unique names.
+When an attribute and a method have the same name, Python gives the attribute precedence. Because two objects cannot have the same name while residing in the same namespace, the method will effectively be hidden. If you try to call the method, Python will actually attempt to call the attribute, a ``TypeError`` runtime error will occur, and the module will not successfully execute. Therefore when you encounter this error you must modify the attribute and method to have unique names.
 
 This error often occurs when somebody implements a getter/setter method for accessing an instance attribute. Python style conventions actually prefers that you remove the getter/setter method and just access the attribute directly.
 
diff --git a/docs/correctness/arguments_number_differs_from_method.rst b/docs/correctness/arguments_number_differs_from_method.rst
@@ -4,17 +4,17 @@ Arguments number differs from method
 Summary
 -------
 
-A child class has implemented an abstract method with a different number of arguments than what is defined in the parent class' method signature. Treat this as a warning. The child class' implementation should match the argument signature defined in the the parent class.
+A child class has implemented an abstract method with a different number of arguments than what is defined in the method signature of the parent class. Treat this error as a warning. The child class' implementation should match the argument signature defined in the parent class.
 
 Description
 -----------
 
-If the child class' implementation of the parent class' abstract method contains more arguments than the method signature in the parent class, Python will be able to execute the method. If the child class' implementation has less arguments than what is defined in the parent class' abstract method signature, then Python will not be able to execute the method. Either way, this defeats the purpose of abstract methods. Abstract methods are contracts passed down to inherited classes which signify that the parent class expects its children to implement a method that matches a particular argument signature. When the child class does not match the signature defined in the parent class, it is not fulfilling its part of the inheritance contract.
+There are two outcomes that can occur when the number of arguments in a child class implementation does not match the abstract method signature in the parent class. If the child class contains more arguments than the parent class, then Python can execute the code. If the number of arguments in the child class is less than the parent class abstract method signature, then Python cannot execute the code. Either way, this defeats the purpose of abstract methods. Abstract methods are contracts passed down to inherited classes from parent classes. The children are supposed to implement a method that matches the argument signature defined by the parent. When the child class does not match the signature defined in the parent class, it is not fulfilling its part of the inheritance contract.
 
 Examples
 ----------
 
-Child class method contains more arguments than parent class' method signature
+Child class method contains more arguments than parent class method signature
 ..............................................................................
 
 In the module below ``Dog`` is a child class of ``Animal``. ``Dog`` is supposed to implement a class called ``print_class_information`` that takes no arguments. However, ``Dog``'s implementation accepts one argument, ``biological_family``.
diff --git a/docs/correctness/assigning_to_function_call_which_only_returns_none.rst b/docs/correctness/assigning_to_function_call_which_only_returns_none.rst
@@ -40,7 +40,7 @@ Note that the ``Assigning to function call which only returns once`` is NOT rais
 
     def hello():
         print "hello"
-        return
+        return  # although this is equivalent to Return None, error is not raised (but it should be)
 
     v = hello()
     print v # WARNING: always returns None, but error not raised!
diff --git a/docs/correctness/bad_first_argument_given_to_super.rst b/docs/correctness/bad_first_argument_given_to_super.rst
@@ -9,7 +9,7 @@ The first argument to ``super()`` should be the class name of the child class th
 Description
 -----------
 
-``super()`` enables you to access the methods and members of a parent class without referring to the parent class by name. For a single inheritance situation the first argument to ``super()`` should be the name of the current child class calling ``super()``, and the second argument should be ``self``, that is, a reference to the current object calling ``super()``.
+``super()`` enables you to access the methods and members of a parent class without referring to the parent class by name. For a single inheritance situation the first argument to ``super()`` should be the name of the current child class calling ``super()``, and the second argument should be ``self`` (that is, a reference to the current object calling ``super()``).
 
 Examples
 ----------
diff --git a/docs/correctness/class_has_no_init_method.rst b/docs/correctness/class_has_no_init_method.rst
@@ -23,7 +23,7 @@ The ``Car`` class triggers the ``class has no __init__ method`` warning because
 
 .. code:: python
 
-    class Car:
+    class Car:  # class defines no __init__ method
         def print_class_name(self):
             print "Car"
 
diff --git a/docs/correctness/class_has_no_member.rst b/docs/correctness/class_has_no_member.rst
@@ -14,8 +14,8 @@ When a module attempts to use a member of a class which is not defined in that c
 Examples
 ----------
 
-Description of error
-....................
+Reference to unimplemented member
+.................................
 
 The module below attempts to call a function from the ``Rectangle`` class called ``area``. This raises the ``class has no member`` error because the ``area`` function in undefined in the ``Rectangle`` class. 
 
diff --git a/docs/correctness/do_not_assign_a_lambda_expression.rst b/docs/correctness/do_not_assign_a_lambda_expression.rst
@@ -4,7 +4,7 @@ Do not assign a ``lambda`` expression, use a ``def``
 Summary
 -------
 
-Assigning a name to a ``lambda`` essentially duplicates the functionality of ``def``, in which case you should just use a ``def`` in order to avoid confusion and increase clarity.
+Assigning a name to a ``lambda`` essentially duplicates the functionality of ``def`` (a function definition), in which case you should just use a ``def`` in order to avoid confusion and increase clarity.
 
 Description
 -----------
diff --git a/docs/correctness/duplicate_argument_name_in_function_definition.rst b/docs/correctness/duplicate_argument_name_in_function_definition.rst
@@ -9,7 +9,7 @@ Two or more parameters in a function definition have the exact same name. Give e
 Description
 -----------
 
-When two or more parameters have the same name in a function definition, Python cannot resolve which parameter is being referenced whenever that name is used. The only solution to this situation is to give each name a unique meaning. This is a good programming practice in general; names should not be overloaded with multiple meanings.
+When two or more parameters have the same name in a function definition, Python cannot resolve which parameter is being referenced. The only solution to this situation is to give each parameter a unique name. This is a good programming practice in general; names should not be overloaded with multiple meanings.
 
 Examples
 ----------
diff --git a/docs/correctness/else_clause_on_loop_without_a_break_statement.rst b/docs/correctness/else_clause_on_loop_without_a_break_statement.rst
@@ -17,7 +17,7 @@ Examples
 Loop contains ``else`` clause yet specifies no ``break`` statements
 ...................................................................
 
-The code below demonstrates some potential unintended behavior that can result when a loop contains an ``else`` statement yet never specifies a ``break`` statement. ``contains_magic_number()`` iterates through a list of numbers and compares each number to the magic number. If the magic number is found then the function prints ``The list contains the magic number."``. If it doesn't then the function prints ``This list does NOT contain the magic number.``. When the module calls the function with a list of ``range(10)`` and a magic number of ``5``, you would expect the module to only print ``The list contains the magic number.``. However, the module also prints ``This list does NOT contain the magic number.``. This is because when the ``range(10)`` list eventually becomes empty, which prompts Python to execute the ``else`` clause.
+The code below demonstrates some potential unintended behavior that can result when a loop contains an ``else`` statement yet never specifies a ``break`` statement. ``contains_magic_number()`` iterates through a list of numbers and compares each number to the magic number. If the magic number is found then the function prints ``The list contains the magic number."``. If it doesn't then the function prints ``This list does NOT contain the magic number.``. When the module calls the function with a list of ``range(10)`` and a magic number of ``5``, you would expect the module to only print ``The list contains the magic number.``. However, the module also prints ``This list does NOT contain the magic number.``. This is because the ``range(10)`` list eventually becomes empty, which prompts Python to execute the ``else`` clause.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
diff --git a/docs/correctness/future_import_is_not_the_first_statement.rst b/docs/correctness/future_import_is_not_the_first_statement.rst
@@ -4,7 +4,7 @@
 Summary
 -------
 
-Features from the ``__future__`` module need to be imported before all other executable statements in the module or else Python will raise a ``SyntaxError`` and the program will not execute. This prevents a module from being able to simultaneously use incompatible versions of a Python feature, which would be highly likely to cause nasty bugs.
+Features from the ``__future__`` module need to be imported before all other executable statements in the module or else Python will raise a ``SyntaxError`` and the program will not execute. Raising a ``SyntaxError`` in this scenario prevents a module from being able to simultaneously use incompatible versions of a Python feature, which would be highly likely to cause nasty bugs.
 
 Description
 -----------
@@ -17,7 +17,7 @@ Examples
 Module imports from ``__future__`` after other statements
 .........................................................
 
-The module below attempts to place a ``__future__`` import statement in the middle of the module. When Python encounters the ``from __future__ import division`` statement it raises a ``SyntaxError`` and halts execution. However, if the module were to execute, the first ``print`` statement would print out ``1`` (which is how the division operator behaves in Python versions 2 and below), but the second ``print`` statement would print out a decimal value, which is how the division operator functions in Python versions 3 and later. As you can see, this could create very strange behavior, so Python does not allow ``__future__`` import statements in the middle of a module. The module must can use either version of the division operator, but it can't use both.
+The module below attempts to place a ``__future__`` import statement in the middle of the module. When Python encounters the ``from __future__ import division`` statement it raises a ``SyntaxError`` and halts execution. However, if the module were to execute, the first ``print`` statement would print out ``1`` (which is how the division operator behaves in Python versions 2 and below), but the second ``print`` statement would print out a decimal value, which is how the division operator functions in Python versions 3 and later. As you can see, this could create very strange behavior, so Python does not allow ``__future__`` import statements in the middle of a module. The module can use either version of the division operator, but it can't use both.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
diff --git a/docs/correctness/implementing_java-style_getters_and_setters.rst b/docs/correctness/implementing_java-style_getters_and_setters.rst
@@ -17,7 +17,7 @@ Examples
 Implementing Java-style getters and setters
 ...........................................
 
-The programmer below comes to Python from a long career as a Java programmer. For every class member that he wants to expose publicly, he defines a ``get`` and ``set`` method for that member. This is common practice in Java, but is frowned upon in Python as a waste of time and unnecessary code.
+The programmer below comes to Python from a long career as a Java programmer. For every class member that he wants to expose publicly, he defines a ``get`` and ``set`` method for that member. This is common practice in Java, but is frowned upon in Python as a waste of time and a cause of unnecessary code.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
diff --git a/docs/correctness/indentation_contains_mixed_spaces_and_tabs.rst b/docs/correctness/indentation_contains_mixed_spaces_and_tabs.rst
@@ -4,12 +4,12 @@ Indentation contains mixed spaces and tabs
 Summary
 -------
 
-The code is being indented with both spaces and tabs. Python code should be indented with 4 spaces.
+The code is being indented with both spaces and tabs. Python code should be indented with 4 spaces, never tabs.
 
 Description
 -----------
 
-Per the PEP 8 Style Guide, all Python code should be consistently indented with 4 spaces, not tabs.
+Per the PEP 8 Style Guide, all Python code should be consistently indented with 4 spaces, never tabs.
 
 Examples
 --------
diff --git a/docs/correctness/indentation_contains_tabs.rst b/docs/correctness/indentation_contains_tabs.rst
@@ -19,7 +19,7 @@ Code is indented with spaces and tabs
 
 The following code uses tabs for indentation. Python code should be indented with four spaces for each level of indentation.
 
-.. warning:: WARNING! The code below is an example of an error. Using this code will create bugs in your programs!
+.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
 .. code:: python
 
diff --git a/docs/correctness/init_method_from_base_class_not_called.rst b/docs/correctness/init_method_from_base_class_not_called.rst
@@ -19,7 +19,7 @@ Derived class does not call base class' ``__init__`` method
 
 The class ``Male`` is a descendant of the class ``Person``. Because the ``Male`` class does not call the ``__init__`` method of ``Person``, the members and methods defined in ``Person`` are not accessible to ``Male`` class instances. Attempting to use base class members and methods results in runtime errors.
 
-.. warning:: WARNING! The code below is an example of an error. Using this code will create bugs in your programs!
+.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
 .. code:: python
 
diff --git a/docs/performance/using_key_in_list_to_check_if_key_is_contained_in_a_list.rst b/docs/performance/using_key_in_list_to_check_if_key_is_contained_in_a_list.rst
@@ -9,7 +9,7 @@ Using ``key in list`` to check if an item is contained in a list is not an error
 Description
 -----------
 
-Using ``key in list`` to iterate through a list can potentially take ``n`` iterations to complete, where ``n`` is the number of items in the list. If possible, you should change the list to a set or dictionary instead, becase Python can search for items in a set or dictionary by attempting to directly accessing them without using any iterations, which is much more efficient.
+Using ``key in list`` to iterate through a list can potentially take ``n`` iterations to complete, where ``n`` is the number of items in the list. If possible, you should change the list to a set or dictionary instead, becase Python can search for items in a set or dictionary by attempting to directly accessing them without iterations, which is much more efficient.
 
 Examples
 ----------
@@ -25,7 +25,7 @@ The module below defines a list ``l`` and then calls ``if 3 in l`` to check if t
 
     l = [1, 2, 3, 4]
     
-    if 3 in l:
+    if 3 in l:  # iterates through list three times
         print "The number 3 is in the list."
     else:
         print "The number 3 is NOT in the list."
