mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 14:50:19 +00:00
Merge pull request #179 from campbellr/master
Fix several spelling mistakes
This commit is contained in:
Kenneth Reitz
+2
-2
@@ -15,7 +15,7 @@ VIM
|
||||
Vim is a text editor which uses keyboard shortcuts for editing instead of menus
|
||||
or icons. There exist a couple of plugins and settings for the VIM editor to
|
||||
aid python development. If you only develop in Python, a good start is to set
|
||||
the default settings for indentation and linewrapping to values compliant with
|
||||
the default settings for indentation and line-wrapping to values compliant with
|
||||
`PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_. In your home directory,
|
||||
open a file called `.vimrc` and add the following lines: ::
|
||||
|
||||
@@ -162,7 +162,7 @@ Create a virtual environment for a project::
|
||||
$ cd my_project
|
||||
$ virtualenv venv
|
||||
|
||||
``virtualenv venv`` will create a folder in the currect directory
|
||||
``virtualenv venv`` will create a folder in the current directory
|
||||
which will contain the Python executable files, and a copy of the ``pip``
|
||||
library which you can use to install other packages. The name of the
|
||||
virtual environment (in this case, it was ``venv``) can be anything;
|
||||
|
||||
@@ -136,7 +136,7 @@ as writing C extensions.
|
||||
The Python Language Reference
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is Python's reference manual, it covers the syntax and the core symantics of the
|
||||
This is Python's reference manual, it covers the syntax and the core semantics of the
|
||||
language.
|
||||
|
||||
`The Python Language Reference <http://docs.python.org/reference/index.html>`_
|
||||
`The Python Language Reference <http://docs.python.org/reference/index.html>`_
|
||||
|
||||
@@ -7,7 +7,7 @@ The Guide Style Guide
|
||||
As with all documentation, having a consistent formating helps make the
|
||||
document more understandable. In order to make The Guide easier to digest,
|
||||
all contributions should fit within the rules of this style guide where
|
||||
approriate.
|
||||
appropriate.
|
||||
|
||||
The Guide is written as :ref:`restructuredtext-ref`.
|
||||
|
||||
@@ -29,9 +29,9 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide
|
||||
Be sure to describe what and why you are linking.
|
||||
* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
|
||||
references where needed.
|
||||
* If a subject isn't directly relevant to Python, but useful in conjuction
|
||||
* If a subject isn't directly relevant to Python, but useful in conjunction
|
||||
with Python (ex: Git, Github, Databases), reference by linking to useful
|
||||
resouces and describe why it's useful to Python.
|
||||
resources and describe why it's useful to Python.
|
||||
* When in doubt, ask.
|
||||
|
||||
Headings
|
||||
@@ -115,7 +115,7 @@ Externally Linking
|
||||
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
|
||||
|
||||
* Avoid using labels such as "click here", "this", etc. preferring
|
||||
decriptive labels (SEO worthy) instead.
|
||||
descriptive labels (SEO worthy) instead.
|
||||
|
||||
Linking to Sections in The Guide
|
||||
--------------------------------
|
||||
|
||||
@@ -35,7 +35,7 @@ simply run
|
||||
|
||||
$ /usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
|
||||
|
||||
Then, insert the Homebrew directory at the top of your ``PATH`` enviornment
|
||||
Then, insert the Homebrew directory at the top of your ``PATH`` environment
|
||||
variable. You can do this by adding the following line at the bottom of your
|
||||
``~/.bashrc`` file
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ misleading for the maintainers, slow down considerably bug hunting or
|
||||
refactoring, and then, when discovered wrong, they will throw suspicion on all
|
||||
other comments in the code, regardless of their individual correctness.
|
||||
|
||||
**No need comments for perfect code...** An hypothetical perfectly readable
|
||||
**There's no need to comment perfect code...** An hypothetical perfectly readable
|
||||
code, with a crystal clear logic stream, expressive variable and function
|
||||
names, orthogonal segmentation passing exactly between the flesh and the bones,
|
||||
and no implicit assumptions of any kind, would not require any comment at all.
|
||||
@@ -78,7 +78,7 @@ When striving for coding excellence, it is useful to see any existing comment,
|
||||
or any feeling of a need for a comment, as the sign that the code do not
|
||||
express clearly enough its intent and can be improved.
|
||||
|
||||
**.. but no code is perfect.** Perfect code is a chimere, it exists only in
|
||||
**.. but no code is perfect.** Perfect code is a chimera, it exists only in
|
||||
our dreams. In real life, a code base is full of trade offs, and comments are
|
||||
often needed in the most difficult parts. Moreover, any special case, any
|
||||
obscure hack, any monkey patch and any ugly workaround MUST be signaled and
|
||||
@@ -87,15 +87,15 @@ explained by a proper comment. This should be enforced by the law!
|
||||
**TODOs** are special comments that a developer write as a reminder for later
|
||||
use. It is said that its original intent was that someone might, one day,
|
||||
search for the string "TODO" in the code base and actually roll their sleeves
|
||||
and start *to do the TODOs*. There is no avalaible record that it ever
|
||||
and start *to do the TODOs*. There is no available record that it ever
|
||||
happened. However, TODOs comment are still very useful, because they mark the
|
||||
current limits of the code, and it is not unlikely that, when required to add a
|
||||
new behavior to the actual code, looking at the TODOs will show where to start.
|
||||
|
||||
**Do not use triple-quote strings to comment code.** A common operation when
|
||||
modifiying code is to comment out some lines or even a full function or class
|
||||
modifying code is to comment out some lines or even a full function or class
|
||||
definition. This can be done by adding triple-quotes around the code block to
|
||||
be skipped, but this is not a good pratice, because line-oriented command-line
|
||||
be skipped, but this is not a good practice, because line-oriented command-line
|
||||
tools such as ``grep`` will not be aware that the commented code is inactive.
|
||||
It is better to add hashes at the proper indentation level for every commented
|
||||
line. Good editors allow to do this with few keystrokes (ctrl-v on Vim).
|
||||
@@ -156,7 +156,7 @@ Block comment styling should be used when commenting out multiple lines of code.
|
||||
Paragraphs inside a block comment are separated by a line containing a
|
||||
single #.
|
||||
|
||||
Inline comments are used for individual lines and should be used sparingly.: ::
|
||||
In-line comments are used for individual lines and should be used sparingly.: ::
|
||||
|
||||
An inline comment is a comment on the same line as a statement. Inline
|
||||
comments should be separated by at least two spaces from the statement.
|
||||
|
||||
@@ -279,7 +279,7 @@ clearer and thus preferred.
|
||||
Using this mechanism is useful for separating concerns and avoiding
|
||||
external un-related logic 'polluting' the core logic of the function
|
||||
or method. A good example of a piece of functionality that is better handled
|
||||
with decoration is memoization or caching: you want to store the results of an
|
||||
with decoration is memorization or caching: you want to store the results of an
|
||||
expensive function in a table and use them directly instead of recomputing
|
||||
them when they have already been computed. This is clearly not part
|
||||
of the function logic.
|
||||
|
||||
+14
-14
@@ -41,7 +41,7 @@ most explicit and straightforward manner is preferred.
|
||||
def make_complex(x, y):
|
||||
return {'x': x, 'y': y}
|
||||
|
||||
In the good code above, x and y are explicitely received from
|
||||
In the good code above, x and y are explicitly received from
|
||||
the caller, and an explicit dictionary is returned. The developer
|
||||
using this function knows exactly what to do by reading the
|
||||
first and last lines, which is not the case with the bad example.
|
||||
@@ -50,7 +50,7 @@ One statement per line
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
While some compound statements such as list comprehensions are
|
||||
allowed and appreciated for their brevity and their expressivity,
|
||||
allowed and appreciated for their brevity and their expressiveness,
|
||||
it is bad practice to have two disjoint statements on the same line.
|
||||
|
||||
**Bad**
|
||||
@@ -107,10 +107,10 @@ passed another value.
|
||||
|
||||
Calling a function with keyword arguments can be done in multiple ways in Python,
|
||||
for example it is possible to follow the order of arguments in the definition without
|
||||
explicitely naming the arguments, like in ``send('Hello', 'World', 'Cthulhu`, 'God')``,
|
||||
explicitly naming the arguments, like in ``send('Hello', 'World', 'Cthulhu`, 'God')``,
|
||||
sending a blank carbon copy to God. It would also be possible to name arguments in
|
||||
another order, like in ``send('Hello again', 'World', bcc='God', cc='Cthulhu')``.
|
||||
Those two possibilities are better avoided whitout any strong reason to not
|
||||
Those two possibilities are better avoided without any strong reason to not
|
||||
follow the syntax that is the closest to the function definition: ``send('Hello',
|
||||
'World', cc='Cthulhu', bcc='God')``.
|
||||
|
||||
@@ -132,13 +132,13 @@ However, this construct has some drawback and should be used with caution. If a
|
||||
function receives a list of arguments of the same nature, it is often more
|
||||
clear to define it as a function of one argument, that argument being a list or
|
||||
any sequence. Here, if ``send`` has multiple recipients, it is better to define
|
||||
it explicitely: ``send(message, recipients)`` and call it with ``send('Hello',
|
||||
it explicitly: ``send(message, recipients)`` and call it with ``send('Hello',
|
||||
['God', 'Mom', 'Cthulhu'])``. This way, the user of the function can manipulate
|
||||
the recipient list as a list beforhand, and it opens the possibility to pass
|
||||
any sequence, inculding iterators, that cannot be unpacked as other sequences.
|
||||
the recipient list as a list beforehand, and it opens the possibility to pass
|
||||
any sequence, including iterators, that cannot be unpacked as other sequences.
|
||||
|
||||
The **arbitrary keyword argument dictionary** is the last way to pass arguments
|
||||
to functions. If the function requires an undetermined serie of named
|
||||
to functions. If the function requires an undetermined series of named
|
||||
arguments, it is possible to used the ``**kwargs`` construct. In the function
|
||||
body, ``kwargs`` will be a dictionary of all the passed named arguments that
|
||||
have not been caught be other keyword argument in the function signature.
|
||||
@@ -149,8 +149,8 @@ proven necessity to use them, and they should not be used if the simpler and
|
||||
clearer construct is sufficient to express the function's intention.
|
||||
|
||||
It is up to the programmer writing the function to determine which arguments
|
||||
are positional argmuents and which are optional keyword arguments, and to
|
||||
decide wheter to use the advanced techniques of arbitrary argument passing. If
|
||||
are positional arguments and which are optional keyword arguments, and to
|
||||
decide whether to use the advanced techniques of arbitrary argument passing. If
|
||||
the advices above are followed wisely, it is possible and enjoyable to write
|
||||
Python functions that are:
|
||||
|
||||
@@ -164,7 +164,7 @@ Avoid the magical wand
|
||||
|
||||
A powerful tool for hackers, Python comes with a very rich set of hooks and
|
||||
tools allowing to do almost any kind of tricky tricks. For instance, it is
|
||||
possible to change how objects are created and instanciated, it is possible to
|
||||
possible to change how objects are created and instantiated, it is possible to
|
||||
change how the Python interpreter imports modules, it is even possible (and
|
||||
recommended if needed) to embed C routines in Python.
|
||||
|
||||
@@ -222,7 +222,7 @@ output point in the body.
|
||||
|
||||
There are two main cases for returning values in a function: The result of the function
|
||||
return when it has been processed normally, and the error cases that indicate a wrong
|
||||
input paramter or any other reason for the function to not be able to complete its
|
||||
input parameter or any other reason for the function to not be able to complete its
|
||||
computation or task.
|
||||
|
||||
If you do not wish to raise exceptions for the second case, then returning a value, such
|
||||
@@ -610,7 +610,7 @@ sometime but is preferably avoided, because of its fragility: a white space
|
||||
added to the end of the line, after the backslash, will break the code and may
|
||||
have unexpected results.
|
||||
|
||||
A prefered solution is to use parenthesis around your elements. Left with an
|
||||
A preferred solution is to use parenthesis around your elements. Left with an
|
||||
unclosed parenthesis on an end-of-line the Python interpreter will join the
|
||||
next line until the parenthesis is closed. The same behavior holds for curly
|
||||
and square braces.
|
||||
@@ -624,7 +624,7 @@ and square braces.
|
||||
time to say “I’m going to sleep.”"""
|
||||
|
||||
from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \
|
||||
yet_another_nice_functio
|
||||
yet_another_nice_function
|
||||
|
||||
**Good**:
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ Testing Your Code
|
||||
|
||||
Testing your code is very important.
|
||||
|
||||
Getting used to writting the testing code and the running code in parallel is
|
||||
Getting used to writing the testing code and the running code in parallel is
|
||||
now considered a good habit. Used wisely, this method helps you define more
|
||||
precisely your code's intent and have a more decoupled architecture.
|
||||
|
||||
@@ -39,7 +39,7 @@ Some general rules of testing:
|
||||
|
||||
- If you are in the middle of a development and have to interrupt your work, it
|
||||
is a good idea to write a broken unit test about what you want to develop next.
|
||||
When comming back to work, you will have a pointer to where you were and get
|
||||
When coming back to work, you will have a pointer to where you were and get
|
||||
faster on tracks.
|
||||
|
||||
- The first step when you are debugging your code is to write a new test
|
||||
@@ -48,7 +48,7 @@ Some general rules of testing:
|
||||
|
||||
- Use long and descriptive names for testing functions. The style guide here is
|
||||
slightly different than that of running code, where short names are often
|
||||
preferred. The reason is testing functions are never called explicitely.
|
||||
preferred. The reason is testing functions are never called explicitly.
|
||||
``square()`` or even ``sqr()`` is ok in running code, but in testing code you
|
||||
would has names such as ``test_square_of_number_2()``,
|
||||
``test_square_negative_number()``. These function names are displayed when a
|
||||
@@ -61,7 +61,7 @@ Some general rules of testing:
|
||||
purpose is unclear is not very helpful is this case.
|
||||
|
||||
- Another use of the testing code is as an introduction to new developers. When
|
||||
someone will have to work on the code base, runnning and reading the related
|
||||
someone will have to work on the code base, running and reading the related
|
||||
testing code is often the best they can do. They will or should discover the
|
||||
hot spots, where most difficulties arise, and the corner cases. If they have
|
||||
to add some functionality, the first step should be to add a test and, by this
|
||||
@@ -214,7 +214,7 @@ multiple interpreter configurations
|
||||
|
||||
$ pip install tox
|
||||
|
||||
tox allows you to configure complicatated multi-parameter test matrices via a
|
||||
tox allows you to configure complicated multi-parameter test matrices via a
|
||||
simple ini-style configuration file.
|
||||
|
||||
`tox <http://tox.testrun.org/latest/>`_
|
||||
@@ -222,7 +222,7 @@ simple ini-style configuration file.
|
||||
Unittest2
|
||||
---------
|
||||
|
||||
unittest2 is a a backport of Python 2.7's unittest module which has an improved
|
||||
unittest2 is a backport of Python 2.7's unittest module which has an improved
|
||||
API and better assertions over the one available in previous versions of Python.
|
||||
|
||||
If you're using Python 2.6 or below, you can install it with pip
|
||||
|
||||
Reference in New Issue
Block a user