Merge pull request realpython#119 from guibog/master

Kenneth Reitz · Kenneth Reitz · commit 911d8299e031 · 2012-04-22T17:51:56.000-07:00
Adding a reference section with a new book and line continuation style guide.
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -94,3 +94,13 @@ chapters detail best practices with writing documentation, test-driven
 development, version control, and optimization/profiling.
 
     `Expert Python Programming <http://www.packtpub.com/expert-python-programming/book>`_
+
+
+References
+----------
+
+Python in a Nutshell
+~~~~~~~~~~~~~~~~~~~~
+
+Python in a Nutshell, written by Alex Martelli, covers most cross-platform python's usage,
+from its syntax to built-in libraries to advanced topics such as writing C extensions.
diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst
@@ -8,7 +8,7 @@ If so, you do not need to install or configure anything else to use Python. Havi
 Installation Guides
 -------------------
 
-These guides go over the proper installation of :ref:`Python 2.7 <which-python>` for development purproses, as well as distribute, pip, and virtualenv setup.
+These guides go over the proper installation of :ref:`Python 2.7 <which-python>` for development purposes, as well as distribute, pip, and virtualenv setup.
 
 - :ref:`Mac OS X <install-osx>`.
 - :ref:`Microsoft Windows<install-windows>`.
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -8,6 +8,56 @@ Structuring your project properly is extremely important.
 Structure is Key
 ----------------
 
+Thanks to the way imports and module are handled in Python, it is
+relatively easy to structure a python project. Easy, here, means
+actually that you have not many constraints and that the module
+importing model is easy grasp. Therefore, you are left with the
+pure architectural task of drawing the different parts of your
+project and their interactions.
+
+Easy structuration of a project means it is also easy
+to do it poorly. Some signs of a poorly structured projects
+include:
+
+- Multiple and messy circular dependencies: if your classes
+  Table and Chair in furn.py need to import Carpenter from workers.py
+  to answer to a question such as table.isdoneby(),
+  and if convertly the class Carpenter need to import Table and Chair,
+  for example to answer to carpenter.whatdo(), then you
+  have a circular dependency, and will have to resort to
+  fragile hacks such has using import statements inside
+  methods or functions.
+
+- Hidden coupling. Each and every change in Table implementation
+  breaks 20 tests in unrelated test cases because it breaks Carpenter's code,
+  which requires very careful surgery to adapt the change. This means
+  you have too many assumptions about Table in Carpenter's code or the
+  reverse.
+
+- Heavy usage of global state or context: Instead of explicitely
+  passing ``(height, width, type, wood)`` to each other, Table
+  and Carpenter rely on global variables that can be modified
+  and are modified on the fly by different agent. You need to
+  scrutinize all access to this global variables to understand why
+  a rectangular table became a sqaure, and discover that a remote
+  template code is also modifying this context, messing with
+  table dimensions.
+
+- Spaghetti code: Multiple pages of nested if clauses and for loops
+  with a lot of copy-pasted procedural code and no
+  proper segmentation are known as spaghetti code. Python's 
+  meaningful indentation (one of its most controversial feature) make
+  it very hard to maintain this kind of code. So the good news is that
+  you might not see too much of it.
+
+- Ravioli code is more likely in Python: it consists of hundreds of
+  similar little pieces of logic, often classes or objects, without
+  proper structure. If you never can remember if you have to use
+  FurnitureTable, AssetTable or Table, or even TableNew for your
+  task at hand, you might be swimming in ravioli code.
+
+
+
 
 
 Vendorizing Dependencies
@@ -20,4 +70,4 @@ Runners
 
 
 Further Reading
----------------
+---------------
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
@@ -317,3 +317,40 @@ values in before you return
 
     square, cube = math_func(3)
 
+Line Continuations
+~~~~~~~~~~~~~~~~~~
+
+When a logical line of code is longer than the accepted limit, you need to split it over multiple
+physical lines. Python interpreter will join consecutive lines if the last character of the line is
+a backslash. This is helpful 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 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.
+
+**Bad**:
+
+.. code-block:: python
+
+    my_very_big_string = """For a long time I used to go to bed early. Sometimes, \
+        when I had put out my candle, my eyes would close so quickly that I had not even \
+        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
+
+**Good**:
+
+.. code-block:: python
+
+    my_very_big_string = ("For a long time I used to go to bed early. Sometimes, "
+        "when I had put out my candle, my eyes would close so quickly that I had not even "
+        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)
+
+However, more often than not having to split long logical line is a sign that you
+are trying to do too many things at the same time, which may hinder readability.
