Skip to content

Commit e459776

Browse files
committed
Proofread articles.
1 parent c1bfe1d commit e459776

20 files changed

+55
-52
lines changed

docs/readability/asking_for_permission_instead_of_forgiveness_when_working_with_files.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Examples
1717
Checking if file exists
1818
.......................
1919

20-
The module below uses an ``if`` statement to check if a file exists before attempting to use the file. This is not the preferred coding style in the Python community. The community prefers to assume that a file exists and you have access to it, and catch any problems as exceptions.
20+
The module below uses an ``if`` statement to check if a file exists before attempting to use the file. This is not the preferred coding style in the Python community. The community prefers to assume that a file exists and you have access to it, and to catch any problems as exceptions.
2121

2222
.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
2323

docs/readability/comparison_to_none.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Examples
1515
----------
1616

1717
Statement compares value to ``None`` using ``==``
18-
....................
18+
.................................................
1919

2020
The statement below uses the equality operator to compare a variable to ``None``. This is not the PEP 8 preferred approach to comparing values to ``None``.
2121

@@ -35,7 +35,7 @@ Solutions
3535
Compare values to ``None`` using the pattern ``if cond is None``
3636
.................................................................
3737

38-
The code below refactors the comparison to ``None`` to use the PEP 8 preferred pattern of ``if cond is None``.
38+
The code below uses the PEP 8 preferred pattern of ``if cond is None``.
3939

4040
.. code:: python
4141
@@ -47,5 +47,5 @@ The code below refactors the comparison to ``None`` to use the PEP 8 preferred p
4747
4848
References
4949
----------
50-
- `PEP 8 Style Guide - Progrmaming Recommendations <http://legacy.python.org/dev/peps/pep-0008/#programming-recommendations>`_
5150
- pep8 - E711
51+
- `PEP 8 Style Guide - Progrmaming Recommendations <http://legacy.python.org/dev/peps/pep-0008/#programming-recommendations>`_

docs/readability/comparison_to_true.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Examples
1515
----------
1616

1717
Statement compares value to ``True`` using ``==``
18-
....................
18+
..................................................
1919

2020
The statement below uses the equality operator to compare a boolean variable to ``True``. This is not the PEP 8 preferred approach to comparing values to ``True``.
2121

@@ -35,7 +35,7 @@ Solutions
3535
Compare values to ``True`` using the pattern ``if cond is True:``
3636
.................................................................
3737

38-
The code below refactors the comparison to ``True`` to use the PEP 8 preferred pattern of ``if cond is True:``.
38+
The code below uses the PEP 8 preferred pattern of ``if cond is True:``.
3939

4040
.. code:: python
4141
@@ -47,7 +47,7 @@ The code below refactors the comparison to ``True`` to use the PEP 8 preferred p
4747
Compare values to ``True`` using the pattern ``if cond is True:``
4848
.................................................................
4949

50-
The code below refactors the comparison to ``True`` to use the PEP 8 preferred pattern of ``if cond:``. This only works if the object, variable, or expression evaluates to a Boolean value of ``True`` or ``False``.
50+
The code below uses the PEP 8 preferred pattern of ``if cond:``. This only works if the object, variable, or expression evaluates to a Boolean value of ``True`` or ``False``.
5151

5252
.. code:: python
5353
@@ -58,5 +58,5 @@ The code below refactors the comparison to ``True`` to use the PEP 8 preferred p
5858
5959
References
6060
----------
61-
- `PEP 8 Style Guide - Progrmaming Recommendations <http://legacy.python.org/dev/peps/pep-0008/#programming-recommendations>`_
6261
- pep8 - E712
62+
- `PEP 8 Style Guide - Progrmaming Recommendations <http://legacy.python.org/dev/peps/pep-0008/#programming-recommendations>`_

docs/readability/do_not_compare_types_use_isinstance.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Examples
1515
----------
1616

1717
Types compared using ``is``
18-
.........................................
18+
............................
1919

2020
The ``if`` statement below uses the pattern ``if type(OBJECT) is types.TYPE`` to compare a ``Rectangle`` object to a built-in type (``ListType`` in this example). This is not the preferred pattern for comparing types.
2121

@@ -32,10 +32,10 @@ The ``if`` statement below uses the pattern ``if type(OBJECT) is types.TYPE`` to
3232
3333
r = Rectangle(3, 4)
3434
35-
if type(r) is not types.ListType:
35+
if type(r) is not types.ListType: # bad
3636
print "object r is a list"
3737
38-
Note that the following situation will not raise the error.
38+
Note that the following situation will not raise the error, although it should.
3939

4040
.. code:: python
4141
@@ -53,7 +53,7 @@ Note that the following situation will not raise the error.
5353
c = Circle(2)
5454
r = Rectangle(3, 4)
5555
56-
if type(r) is not type(c):
56+
if type(r) is not type(c): # bad
5757
print "object types do not match"
5858
5959
Solutions
@@ -75,7 +75,7 @@ The preferred pattern for comparing types is the built-in function ``isinstance`
7575
7676
r = Rectangle(3, 4)
7777
78-
if isinstance(r, types.ListType):
78+
if isinstance(r, types.ListType): # good
7979
print "object r is a list"
8080
8181
References

docs/readability/incomplete_docstring.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,21 @@ A docstring for a module, function, class, or method is either missing or empty.
99
Description
1010
-----------
1111

12-
Docstrings help you remember the intention of a module, function, class, or method. This is especially important as your codebase grows and it becomes harder to remember the implemenation details of each object.
12+
Docstrings help you remember the intention of a module, function, class, or method. This is especially important as your codebase grows and it becomes harder to remember the implementation details of each object.
1313

1414
Examples
1515
----------
1616

1717
Function missing docstring
1818
..........................
1919

20-
The function below contains no docstring describing its purpose. If you had access to the implementation of the function, then you could tell that it is a function for computing the area of a rectangle. However, if you did not have access to the function implemenation and only had access to the function signature (``def area(width, height):``), you wouldn't be able to tell whether this function computes the area of a triangle or a rectangle. Without a docstring, it is more difficult to understand what this function is used for.
20+
The function below contains no docstring describing its purpose. If you didn't have access to the function implementation and only had access to the function signature (i.e. ``def area(width, height)``), you wouldn't be able to tell whether this function computes the area of a triangle or a rectangle.
2121

2222
.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
2323

2424
.. code:: python
2525
26-
def area(width, height):
26+
def area(width, height): # no docstring, bad
2727
return width * height
2828
2929
Solutions

docs/readability/invalid_name.rst

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Summary
66

77
The name of an object does not match the naming convention for its type (variable, constant, etc.). This error is just a stylistic warning. The code will probably execute. But you can improve the readability of the code by renaming the object to match the naming conventions for that type of object.
88

9+
.. _description:
10+
911
Description
1012
-----------
1113

@@ -30,7 +32,7 @@ Examples
3032
Function name does not follow naming convention
3133
...............................................
3234

33-
The function named ``Hello`` below does not follow the standard naming convention for functions. As indicated in the table above in the "Description" section of this article, functions are supposed to begin with a lower case letter. The problem with ``Hello`` is that it begins with an upper case letter. The program executes, but other programmers may find the code hard to read, because classes are usually the only objects that begin with upper case letters.
35+
The function named ``Hello`` below does not follow the standard naming convention for functions. As indicated in the table above in :ref:`description`, functions are supposed to begin with a lower case letter. The problem with ``Hello`` is that it begins with an upper case letter. The program executes, but other programmers may find the code hard to read, because classes are usually the only objects that begin with upper case letters.
3436

3537
.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
3638

@@ -51,10 +53,10 @@ In the modified module below, the function name has been modified to follow the
5153

5254
.. code:: python
5355
54-
def hello(): # replace H with h
56+
def hello(): # easier to read, looks like a function
5557
print "Hello, World!"
5658
57-
hello() # easier to read, looks like a function
59+
hello() # remember to fix every invocation of function
5860
5961
References
6062
----------

docs/readability/lambda_may_not_be_necessary.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ Lambda may not be necessary
44
Summary
55
-------
66

7-
The body of a lambda expression is just a function call on the same argument list as the lambda itself. The lambda is probably unnecessary. Improve code readability by removing the lambda and calling the function directly on the argument list.
7+
The body of a lambda expression is just a function call on the same argument list as the lambda itself. This lambda is probably unnecessary. Improve code readability by removing the lambda and calling the function directly on the argument list.
88

99
Description
1010
-----------
1111

12-
Lambda expressions enable you to create inline, anonymous functions. A lambda serves no purpose when it is just a call to a named function. It only makes the code harder to read.
12+
Lambda expressions enable you to create inline, anonymous functions. A lambda serves no purpose when it is just a call to a named function. It only makes the code harder to read. Remove the lambda and just call the function directly.
1313

1414
Examples
1515
----------

docs/readability/not_using_a_dict_comprehension.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,20 @@ Not using a dict comprehension
44
Summary
55
-------
66

7-
For Python versions 2.6 and below, a common way to initialize a dict was to pass an iterable of key-value pairs in the dict's constructor (e.g. ``d = dict((key, value) for (key, value) in iterable)``). However, in Python 2.7 and beyond, a new syntax called dict comprehension (e.g. ``d = {key: value for (key, value) in iterable}``) was introduced which is generally more readable and is now the preferred style. Use the new syntax whenever possible.
7+
For Python versions 2.6 and below, a common way to initialize a dict is to pass an iterable of key-value pairs in the dict's constructor (e.g. ``d = dict((key, value) for (key, value) in iterable)``). However, in Python 2.7 and beyond, a new syntax called dict comprehension (e.g. ``d = {key: value for (key, value) in iterable}``) is available. Dict comprehension is generally more readable and is now the preferred style. Use dict comprehension whenever possible.
88

99
Description
1010
-----------
1111

12-
You may encounter the old style of initializing a dict by passing an iterable of key-value pairs in older Python code that was written before version 2.7. The new dict comprehension style is functionally equivalent and is much more readable. Consider refactoring the code to use the new style, assuming that you are now using Python 2.7 or higher.
12+
You may encounter the old style of initializing a dict (passing an iterable of key-value pairs) in older Python code written before version 2.7. The new dict comprehension style is functionally equivalent and is much more readable. Consider refactoring the old-style code to use the new style (but only if you are using Python 2.7 or higher).
1313

1414
Examples
1515
----------
1616

1717
Not using dict comprehension
1818
............................
1919

20-
The module below demonstrates the old syntax of initializing a dict via an iterable of key-value pairs. Although there is nothing wrong with this code, it is somewhat hard to read.
20+
The module below demonstrates the old syntax of dict initialization. Although there is nothing syntactically wrong with this code, it is somewhat hard to read.
2121

2222
.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
2323

docs/readability/not_using_items_to_iterate_over_a_dictionary.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Not using ``items()`` to iterate over a dictionary
44
Summary
55
-------
66

7-
``items()`` is the preferred way to iterate through the key-value pairs of a dictionary. Although there are other valid ways to iterate through a dictionary, this is the most concise way, and you can improve code readability by using the method which is most familiar to the most Python programmers.
7+
``items()`` is the preferred way to iterate through the key-value pairs of a dictionary. Although there are other valid ways to iterate through a dictionary, this is the most concise and common way.
88

99
Description
1010
-----------
@@ -17,16 +17,16 @@ Examples
1717
For loop does not use ``items()`` to iterate across dictionary
1818
...............................................................
1919

20-
The module below defines a for loop that iterates over a dictionary named ``d``. For each loop iteration Python automatically assigns the value of ``k`` to the name of the next key in the dictionary. Inside of the ``for`` loop the module uses ``k`` to access the value of each key of the dictionary. This is a common way for iterating over a dictionary, but it is not the preferred way in Python.
20+
The module below defines a for loop that iterates over a dictionary named ``d``. For each loop iteration Python automatically assigns the value of ``key`` to the name of the next key in the dictionary. Inside of the ``for`` loop the module uses ``key`` to access the value of each key of the dictionary. This is a common way for iterating over a dictionary, but it is not the preferred way in Python.
2121

2222
.. warning:: The code below is an example of an error. Using this code will create bugs in your programs!
2323

2424
.. code:: python
2525
26-
dictionary = {"first_name": "Alfred", "last_name":"Hitchcock"}
26+
d = {"first_name": "Alfred", "last_name":"Hitchcock"}
2727
28-
for key in dictionary:
29-
print "%s = %s".format(key, dictionary[key])
28+
for key in d:
29+
print "%s = %s".format(key, d[key])
3030
3131
Solutions
3232
---------
@@ -38,10 +38,10 @@ The updated module below demonstrates the Pythonic style for iterating through a
3838

3939
.. code:: python
4040
41-
dictionary = {"first_name": "Alfred", "last_name":"Hitchcock"}
41+
d = {"first_name": "Alfred", "last_name":"Hitchcock"}
4242
43-
for key,value in dictionary.items():
44-
print "%s = %s".format(key, value)
43+
for key,val in dictionary.items():
44+
print "%s = %s".format(key, val)
4545
4646
References
4747
----------

docs/readability/not_using_named_tuples_when_returning_more_than_one_value.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ Not using named tuples when returning more than one value from a function
44
Summary
55
-------
66

7-
Use named tuples when returning more than one value from a function. This makes code easier to read and makes the data easier to access, as each value can be accessed via a name in addition to an index.
7+
Use `named tuples <http://stackoverflow.com/questions/2970608/what-are-named-tuples-in-python>`_ when returning more than one value from a function. This makes code easier to read and makes the data easier to access, as each value can be accessed via a name in addition to an index.
88

99
Description
1010
-----------
1111

12-
Named tuples can be used anywhere where normal tuples are acceptable, but their values can be accessed through their name in addition to their index, which makes code more verbose and easier to read.
12+
Named tuples can be used anywhere where normal tuples are acceptable, but their values can be accessed through their names in addition to their indexes. This makes the code more verbose and readable.
1313

1414
Examples
1515
----------
@@ -28,7 +28,7 @@ The module below returns a first name, middle name, and last name using a normal
2828
2929
name = get_name()
3030
31-
print name[0], name[1], name[2] # ('Richard', 'Xavier', 'Jones') # hard to read
31+
print name[0], name[1], name[2] # no idea what these indexes map to!
3232
3333
Solutions
3434
---------

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy