Adding poor project structuration examples

diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index b83f09a..a640277 100644 (file)
--- 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
+---------------