Fix minor spelling, grammar, and consistency errors in the Structure is Key section.
authorJay Roberts <jay@gloryfish.org>
Fri, 11 May 2012 18:08:08 +0000 (14:08 -0400)
committerJay Roberts <jay@gloryfish.org>
Fri, 11 May 2012 18:08:08 +0000 (14:08 -0400)
docs/writing/structure.rst

index 38fde94..7d35b96 100644 (file)
@@ -8,49 +8,49 @@ Structuring your project properly is extremely important.
 Structure is Key
 ----------------
 
-Thanks to the way imports and module are handled in Python, it is
+Thanks to the way imports and modules 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
+that you do not have many constraints and that the module
+importing model is easy to grasp. Therefore, you are left with the
+pure architectural task of crafting 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
+Easy structuring of a project means it is also easy
+to do it poorly. Some signs of a poorly structured project
 include:
 
-- Multiple and messy circular dependencies: if your classes
+- 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
+  to answer a question such as table.isdoneby(),
+  and if conversely the class Carpenter needs to import Table and Chair,
+  to answer the question carpenter.whatdo(), then you
+  have a circular dependency. In this case you 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
+- Hidden coupling: Each and every change in Table's 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
+- Heavy usage of global state or context: Instead of explicitly
   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
+  and are modified on the fly by different agents. You need to
+  scrutinize all access to these global variables to understand why
+  a rectangular table became a square, and discover that 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
+  meaningful indentation (one of its most controversial features) 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
+- 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