From 63a2bfc514e0e4982fdaa64cd1cf63e37cfeaba8 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:31:10 -0600 Subject: [PATCH 1/9] Fix awkward wording in "Comments" section --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 62a8165..8d3a8f1 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -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. From 7d66ac6d2059a31732c38169147e7bac8e983acd Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:32:00 -0600 Subject: [PATCH 2/9] Fix spelling in documentation article --- docs/writing/documentation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 8d3a8f1..a598d43 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -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. From e6cef5d19e543d61acfe146332fce349cf9e4dc5 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:38:06 -0600 Subject: [PATCH 3/9] Fix spelling in learning.rst --- docs/intro/learning.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 22bb10b..0f38d6e 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -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 `_ \ No newline at end of file + `The Python Language Reference `_ From bd770496a29db57659c84aa88ef5a3860646d4b1 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:40:36 -0600 Subject: [PATCH 4/9] fix spelling in env.rst --- docs/dev/env.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 2c4ba03..b1678e5 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -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 `_. In your home directory, open a file called `.vimrc` and add the following lines: :: @@ -151,7 +151,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; From d6f0ec1680570ade2d6e5edba2442525e49e516d Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:43:08 -0600 Subject: [PATCH 5/9] Fix spelling in styleguide.rst --- docs/notes/styleguide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index a96c7b6..edaecc1 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -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 `_ 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 `_ * 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 -------------------------------- From 1cfed040f7595ba58b10539992f942fe7306fd5a Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:46:52 -0600 Subject: [PATCH 6/9] Fix spelling in install/osx.rst --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 7b8603c..3da84a7 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -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 From 0ff26166c62f78d3b911e90e17173d3b04d6b5d0 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:48:42 -0600 Subject: [PATCH 7/9] Fix spelling in structure.rst --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 6765f18..3adf2dc 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -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. From e3eac0c78cdffcd3d539f6167718a8c2016ec305 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:55:49 -0600 Subject: [PATCH 8/9] Fix spelling in style.rst --- docs/writing/style.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index b0279b9..462ffba 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -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**: From 1d63c913bf524dbbed03726373ace42e99123231 Mon Sep 17 00:00:00 2001 From: Ryan Campbell Date: Tue, 3 Jul 2012 21:56:06 -0600 Subject: [PATCH 9/9] Fix spelling in writing/tests.rst --- docs/writing/tests.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 0a8479d..12590b6 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -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 `_ @@ -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