Proofread files.

kaycebasques · kaycebasques · commit 73c29a1732d7 · 2014-11-02T16:03:19.000-08:00
diff --git a/docs/maintainability/duplicate_key_in_dictionary.rst b/docs/maintainability/duplicate_key_in_dictionary.rst
@@ -22,17 +22,17 @@ In the module below the ``gmt`` key has been defined twice. When you print out t
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
 .. code:: python
-
+    # first occurrence of 'gmt' below gets silently overridden
     time = {"gmt": -08, "hour": 16, "minute": 37, "second": 05, "gmt": -09}
     print time  # {'second': 05, 'minute': 37, 'hour': 16, 'gmt': -09}
 
 Solutions
 ---------
 
-Delete duplicate keys
-.....................
+Delete or rename duplicate keys
+...............................
 
-In the modified module below the second, duplicate entry for ``gmt`` has been deleted.
+In the modified module below the second, duplicate entry for ``gmt`` has been deleted. Where applicable, another acceptable solution is to give unique names to each of the conflicting items.
 
 .. code:: python
 
diff --git a/docs/maintainability/from_module_import_all_used.rst b/docs/maintainability/from_module_import_all_used.rst
@@ -23,23 +23,22 @@ The following code imports everything from the ``math`` built-in Python module.
 
 .. code:: python
 
-    from math import *
+    from math import *  # wildcard import = bad
 
 Solutions
 ---------
 
 Make the ``import`` statement more specific
 ...........................................
 
-The ``import`` statement should be refactored to be more specific about what functions or variables it is using from the ``math`` module.
+The ``import`` statement should be refactored to be more specific about what functions or variables it is using from the ``math`` module. The modified module below specifies exactly which module member it is using, which happens to be ``ceil`` in this example.
 
 .. code:: python
 
     from math import ceil
 
-
 References
 ----------
-- `Stack Overflow - Importing Modules <http://stackoverflow.com/questions/15145159/importing-modules-how-much-is-too-much>`_
 - PyFlakes - F403
+- `Stack Overflow - Importing Modules <http://stackoverflow.com/questions/15145159/importing-modules-how-much-is-too-much>`_
 
diff --git a/docs/maintainability/import_module_shadowed_by_loop_variable.rst b/docs/maintainability/import_module_shadowed_by_loop_variable.rst
@@ -4,7 +4,7 @@ Import module from line n shadowed by loop variable
 Summary
 -------
 
-A loop has defined a variable with the same name as an imported module. This can cause bugs in a module because it overrides the meaning of the module name. Attempting to access module members after the module name has been redefined can result in runtime errors or unintended behavior. The variable name should be renamed to something other than a module name.
+A loop has defined a variable with the same name as an imported module. This can cause bugs in a module because it overrides the meaning of the module name. Attempting to access members from the overridden module can result in runtime errors or unintended behavior. The variable name should be renamed to something other than a module name.
 
 Description
 -----------
@@ -17,7 +17,7 @@ Examples
 Loop defines variable with same name as imported module
 .......................................................
 
-The module below imports the ``os`` Python Standard Library module, which is used for performing miscellaneous tasks related to the current operating system. When ``os.name`` is called, ``os`` still refers to the ``os`` module, so this works fine. But when the for loop creates a variable called ``os`` this overrides the meaning of ``os``. ``os`` now refers to a ``str`` variable. So only members from the ``str`` class are valid on ``os`` now. Any attempt to reference a member from the ``os`` module creates runtime errors. In other words, when the module attempts to reference ``os.name`` in the for loop, it is actually calling ``str.name``. Because the ``str`` data type does not have any member called ``name`` Python raises an error.
+The module below imports the ``os`` Python Standard Library module, which is used for performing miscellaneous tasks related to the current operating system. When ``os.name`` is called outside of the loop, ``os`` still refers to the ``os`` module, so this works fine. But notice that the for loop also creates a variable called ``os``. This overrides the meaning of ``os``. ``os`` now refers to a ``str`` variable. So only members from the ``str`` class are valid on ``os`` now. Any attempt to reference a member from the ``os`` *module* creates runtime errors. In other words, when the module attempts to reference ``os.name`` in the for loop, it is actually calling ``str.name``. Because the ``str`` data type does not have any member called ``name`` Python raises an error.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
diff --git a/docs/maintainability/module_imported_but_not_used.rst b/docs/maintainability/module_imported_but_not_used.rst
@@ -10,7 +10,7 @@ An imported module is not being used. The ``module imported but not used`` error
 Description
 -----------
 
-This error typically means that there is an error in the module implementation, so you should review the module under question. There are typically three ways to solve the ``module imported but not used`` error. You can remove the module if it is not needed, check that all sections of the module have been fully implemented (and implement them if not), and check for misspellings of the module name, or any of the public objects available from the module (and fix the mispellings).
+This error typically means that there is an error in the module implementation, so you should review the module under question. There are typically three ways to solve the ``module imported but not used`` error. You can remove the module if it is not needed, check that all sections of the module have been fully implemented (and implement them if not), and check for misspellings of the module name or any of the public objects available from the module (and fix the mispellings).
 
 Examples
 ----------
@@ -35,14 +35,14 @@ Solutions
 Remove the module
 .................
 
-Upon reviewing the module, the owner of the module decided that the ``math`` module was not needed, so he removed the ``import math`` statement. Because the module is no longer imported the ``module imported but not used`` error is no longer valid.
+Upon reviewing the module, the owner of the module decided that the ``math`` module was not needed, so he removed the ``import math`` statement. Because the module is no longer imported the ``module imported but not used`` error is no longer raised.
 
 .. code:: python
 
     # removed import math from here
     import time
 
-    print "Current UNIX Epoch time:", math.floor(time.time())
+    print "Current UNIX Epoch time:", time.time()
 
 Use the module
 ..............
diff --git a/docs/maintainability/not_using_with_to_open_files.rst b/docs/maintainability/not_using_with_to_open_files.rst
@@ -4,7 +4,7 @@ Not using ``with`` to open files
 Summary
 -------
 
-Use a ``with`` statement to open a filei (e.g. ``with open("file.txt", "r" as f``). This is the standard and safest way to open a file in Python.
+Use a ``with`` statement to open a file (e.g. ``with open("file.txt", "r" as f``). This is the standard and safest way to open a file in Python.
 
 Description
 -----------
diff --git a/docs/maintainability/redefining_built-in.rst b/docs/maintainability/redefining_built-in.rst
@@ -9,7 +9,7 @@ Raised when the function in a user-defined module has the same name as a `Python
 Description
 -----------
 
-When a user-defined function has the same name as a function from a Python Standard Library, the ``Redefining built-in %r`` error is raised, where ``%r`` is the name of the function that is being overloaded with two or more names. Overloading functions is generally a bad programming practice and should be avoided at all costs.
+When a user-defined function has the same name as a function from a Python Standard Library, the ``Redefining built-in %r`` error is raised, where ``%r`` is the name of the function that is being overloaded with two or more names. Overloading functions is generally a bad programming practice and should be avoided as much as possible.
 
 Examples
 ----------
diff --git a/docs/maintainability/redefinition_of_unused_name.rst b/docs/maintainability/redefinition_of_unused_name.rst
@@ -25,7 +25,7 @@ The module below imports the ``json`` module from the Python Standard Library an
 
     import json
 
-    json = ['{"first": "John", "last": "Smith"', '"ssn": "613230789"']  # redefinition
+    json = ['"first": "John"', '"last": "Smith"', '"ssn": "613230789"']  # redefinition
 
     for s in json:
         print s
@@ -36,13 +36,13 @@ Solutions
 Rename the variable
 ...................
 
-Often the simplest solution for suppressing the ``redefinition of unused name`` error is to give the objects different, unique names. Because the names are unique, there is no more redefinition taking place, and therefore the error is no longer valid. In the modified module below, the variable storing a list of JSON strings has been changed from ``json`` to ``json_list``.
+Often the simplest solution for suppressing the ``redefinition of unused name`` error is to give the objects different, unique names. Because the names are unique, there is no more redefinition taking place, and therefore the error is no longer raised. In the modified module below, the variable storing a list of JSON strings has been changed from ``json`` to ``json_list``.
 
 .. code:: python
 
     import json
 
-    json_list = ['{"first": "John", "last": "Smith"', '"ssn": "613230789"']  # ok now, unique name
+    json_list =  ['"first": "John"', '"last": "Smith"', '"ssn": "613230789"']  # ok now
 
     for s in json_list:
         print s
@@ -54,7 +54,9 @@ Another way to suppress the ``redefinition of unused name`` error is to remove t
 
 .. code:: python
 
-    json = ['{"first": "John", "last": "Smith"', '"ssn": "613230789"']  # ok now, no more redefinition
+    # deleted import statement, no more overriding of names
+
+    json =   ['{"first": "John", "last": "Smith"', '"ssn": "613230789"']
 
     for s in json:
         print s
diff --git a/docs/maintainability/returning_more_than_one_variable_type_from_function_call.rst b/docs/maintainability/returning_more_than_one_variable_type_from_function_call.rst
@@ -24,7 +24,7 @@ Examples
 Function returns ``None`` upon unsatisfied precondition
 .......................................................
 
-In the module below, the function ``get_secret_code()`` returns a secret code when the module calling the function provides the correct password. If the password is incorrect, the function returns ``None``. This leads to hard-to-maintain code, because the caller will have check the type of the return value before proceeding.
+In the module below, the function ``get_secret_code()`` returns a secret code when the module calling the function provides the correct password. If the password is incorrect, the function returns ``None``. This leads to hard-to-maintain code, because the caller will have to check the type of the return value before proceeding.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
diff --git a/docs/maintainability/the_loop_may_never_terminate.rst b/docs/maintainability/the_loop_may_never_terminate.rst
@@ -4,7 +4,7 @@ The loop may never terminate
 Summary
 -------
 
-The given loop does not modify anything that impacts the loop condition and does not call ``break``, ``return``, or ``yield`` explicitly, which may lead to an infinite loop.
+The given loop does not modify anything that impacts the loop condition and does not call ``break``, ``return``, or ``yield`` explicitly. Therefore, this loop will probably never terminate.
 
 Description
 -----------
@@ -35,7 +35,7 @@ Solutions
 Modify the variable that impacts the loop condition
 ...................................................
 
-In the modified module below, the loop will finish executing as expected, because now the variable ``i`` is incremented by 1 in every iteration of the loop.
+In the modified module below, the loop finishes as expected, because now the variable ``i`` is incremented by 1 in every iteration of the loop.
 
 .. code:: python
 
diff --git a/docs/maintainability/too_many_arguments_for_format_string.rst b/docs/maintainability/too_many_arguments_for_format_string.rst
@@ -4,12 +4,12 @@ Too many arguments for format string
 Summary
 -------
 
-A format string contains more arguments than replacement fields. You can improve the readability and minimize the chance of bugs in the code by updating the format string to have the same number of replacement fields and arguments.
+A format string contains more arguments than replacement fields. Fix the format string so that it has the same number of replacement fields as argument strings to minimize bugs and improve readability.
 
 Description
 -----------
 
-Although a format string that contains more arguments than replacement fields will execute just fine, the extra arguments are unused. This reduces code readability and increases the chance of future bugs. Therefore, unless the extra arguments serve a purpose they should be removed. 
+Although a format string that contains more arguments than replacement fields will execute, the extra arguments reduce code readability and increase the chance of future bugs. Therefore, unless the extra arguments serve a purpose they should be removed. 
 
 Examples
 ----------
@@ -32,17 +32,17 @@ Solutions
 Remove extra arguments 
 ......................
 
-Now that the format string contains the same number of replacement fields (two) as arguments (two), the ``too many arguments for format string`` error is suppressed.
+The modified module below suppresses the ``too many arguments for format string`` error by fixing the format string to have the same number of replacement fields as arguments.
 
 .. code:: python
 
-    numbers = "{:d} {:d}".format(1, 2)  # removed the third argument
+    numbers = "{:d} {:d}".format(1, 2)  # removed the extra, third argument
     print numbers
     
 Add more replacement fields
 ...........................
 
-The modified module below adds another replacement field to the string literal to match the number of arguments passed to ``format()``.
+The modified module below adds another replacement field to the string literal to match the number of arguments passed to ``format()``. This is another way to fix the format string to have the same number of replacement fields as arguments.
 
 .. code:: python
 
diff --git a/docs/maintainability/undefined_name_in_all.rst b/docs/maintainability/undefined_name_in_all.rst
@@ -15,7 +15,7 @@ Examples
 ----------
 
 Object not implemented
-..................................
+......................
 
 In the module ``colors`` below, the author forgot to implement the ``brown`` variable but included it in the modules ``__all__`` list. Including an entry in ``__all__`` that does not correspond to any object defined in the module raises the ``Undefined name in __all__`` error.
 
@@ -35,7 +35,7 @@ Solutions
 Implement the object
 ....................
 
-If the object should be exposed in ``__all__`` but it has not been implemented, then implementing the object will eliminate the ``Undefined name is __all__`` error.
+One way to suppress the ``undefined name in __all__`` error is to implement the missing object, like the updated module below.
 
 .. code:: python
 
@@ -48,7 +48,7 @@ If the object should be exposed in ``__all__`` but it has not been implemented,
 Remove the object from the ``__all__`` list
 ...........................................
 
-If the object is private (meaning it should not be listed in ``__all__`` or if the object is not implemented, then removing it from the ``__all__`` list will also suppress the ``Undefined name is __all__`` error.
+If the object is private (meaning it should not be listed in ``__all__``) or if the object is not implemented, then removing it from the ``__all__`` list also suppresses the ``Undefined name in __all__`` error.
 
 .. code:: python
 
diff --git a/docs/maintainability/unused_import_from_wildcard_import.rst b/docs/maintainability/unused_import_from_wildcard_import.rst
@@ -9,7 +9,7 @@ A wildcard import statement is used in the module, but the module does not use e
 Description
 -----------
 
-`EP 20, The Zen of Python <http://legacy.python.org/dev/peps/pep-0020/>`_, states that "Explicit is better than implicit." Import statements of the pattern ``from MODULE import OBJECT`` are more explicit than ``from MODULE import *``. Therefore, you should not use wildcard imports but rather should explicitly list which objects you need to use when importing modules. Wildcard imports also make it more difficult for static code analyzers (like this tool) to perform their jobs.
+`PEP 20, The Zen of Python <http://legacy.python.org/dev/peps/pep-0020/>`_, states that "Explicit is better than implicit." Import statements of the pattern ``from MODULE import OBJECT`` are more explicit than ``from MODULE import *``. Therefore, you should not use wildcard imports but rather should explicitly list which objects you need to use when importing modules. Wildcard imports also make it more difficult for static code analyzers (like this tool) to perform their jobs.
 
 Examples
 ----------
diff --git a/docs/maintainability/unused_variable.rst b/docs/maintainability/unused_variable.rst
@@ -4,12 +4,12 @@ Unused variable
 Summary
 -------
 
-A variable has been defined but is not being used. Review the module in question. Check if the module is missing any implemenatation. To improve code readability and performance, delete the variable in question if it is no longer needed.
+A variable has been defined but is not being used. Review the module in question and check if the module is missing any implemenatation. To improve code readability and performance, delete the variable in question if it is no longer needed.
 
 Description
 -----------
 
-This error is often triggered when someone refactors a module but misses a reference to a variable that is no longer needed. Other times it indicates that someone has forgot to implement a section of the module's logic. Therefore, treat this error as a warning and review the code in question.
+This error is often triggered when someone refactors a module but misses a reference to a variable that is no longer needed. Other times it indicates that someone has forgotten to implement a section of the module's logic. Therefore, treat this error as a warning and review the code in question.
 
 Examples
 ----------
@@ -35,7 +35,7 @@ Solutions
 Remove the unused variable
 ..........................
 
-Upon reviewing the module, the author decides that the ``banana`` variable serves no purpose so he deletes it. The code is now easier to read and more efficient.
+Upon reviewing the module, the author decides that the ``banana`` variable serves no purpose, so he deletes it. The code is now easier to read, more efficient, and the ``unused variable`` error is suppressed.
 
 .. code:: python
 
diff --git a/docs/maintainability/using_the_global_statement.rst b/docs/maintainability/using_the_global_statement.rst
@@ -59,6 +59,8 @@ Encapsulate the global variables into objects
 
 One common solution for avoiding global variables is to create a class and store related global variables as members of an instantiated object of that class. This results in more compact and safer code.
 
+In the modified module below, the author eliminates the need for the global variables ``WIDTH`` and ``HEIGHT`` by encapsulating this data into a class called ``Rectangle``.
+
 .. code:: python
 
     class Rectangle:
diff --git a/docs/maintainability/wildcard_import.rst b/docs/maintainability/wildcard_import.rst
@@ -17,7 +17,7 @@ Examples
 Wildcard import used
 ....................
 
-The module below imports the ``math`` module from the Python standard library. This library contains a function called ``floor``. The function also defines a function with the same name. When this module is executed, either ``floor`` function could potentially be called. This is especially dangerous if the module attempts to use the value returned by the function anywhere else in the module. In the example below, the module presumably is attempting to call ``math.floor`` to round down the integer supplied as an argument. However, because the module's ``floor`` function was defined after the import, it overrides the ``math.floor`` function. Since a function returns ``None`` by default when no return statement is defined, the ``floor`` function returns ``None``. This causes a ``TypeError`` at runtime when Python attempts to divide ``10`` by ``x``, which equals ``None``.
+The module below imports the ``math`` module from the Python standard library. This library contains a function called ``floor``. The function also defines a function with the same name. When this module is executed, either ``floor`` function could potentially be called. This is especially dangerous if the module attempts to use the value returned by the function anywhere else in the module. In the example below, the module presumably is attempting to call ``math.floor`` to round down the integer supplied as an argument. However, because the module's ``floor`` function was defined after the import, the custom function overrides the ``math.floor`` function. Since a function returns ``None`` by default when no return statement is defined, the ``floor`` function returns ``None``. This causes a ``TypeError`` at runtime when Python attempts to divide ``10`` by ``x``, which evaluates to ``10 / None``.
 
 .. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
 
