From dd0615e9e73d6a4774276ed8755eaf07c6ce8973 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 21:49:05 +0800 Subject: [PATCH 1/4] Add a reference section with Python in a Nutshell --- docs/intro/learning.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index c2a31fb..9a9bada 100644 --- 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 `_ + + +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. From ce3e50a9132bfb03ff9b53fc720ce48f0bb7747e Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 22:02:59 +0800 Subject: [PATCH 2/4] typo --- docs/starting/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 09afe52..c22ced8 100644 --- 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 ` for development purproses, as well as distribute, pip, and virtualenv setup. +These guides go over the proper installation of :ref:`Python 2.7 ` for development purposes, as well as distribute, pip, and virtualenv setup. - :ref:`Mac OS X `. - :ref:`Microsoft Windows`. From f860d3e982615d086ee1072dfff9de1f7537ff03 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 22:43:54 +0800 Subject: [PATCH 3/4] add line continuations in style --- docs/writing/style.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index cc2e8c9..67a9b1f 100644 --- 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. From 2d48df09fc363b6e705d7dcc235071bf2304f0ad Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 23:40:35 +0800 Subject: [PATCH 4/4] Adding poor project structuration examples --- docs/writing/structure.rst | 52 +++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b83f09a..a640277 100644 --- 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 ---------------- \ No newline at end of file +---------------