module naming

epequeno · epequeno · commit f05bad383937 · 2012-07-03T21:08:42.000-05:00
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -75,9 +75,22 @@ As soon as you use `import` statements you use modules. These can be either buil
 modules such as `os` and `sys`, third-party modules you have installed in your
 environment, or your project's internal modules.
 
-Nothing special is required for a Python file to be a module, but the import
-mechanism needs to be understood in order to use this concept properly and avoid
-some issues.
+To keep in line with the style guide, keep module names short, lowercase, and
+be sure to avoid using special symbols like the dot (.) or question mark (?).
+So a file name like `my.spam.py` is one you should try to avoid! Naming this way 
+will interfere with the way python looks for modules.
+
+In this example python expects to find a "spam.py" file in a folder named "my"
+which is not the case. There is an 
+`example <http://docs.python.org/tutorial/modules.html#packages>`_
+ of how the dot should be used available in the python docs.
+
+If you'd like you could name it as `my_spam.py` but even our friend the 
+underscore should not be seen often in module names.
+
+Aside for some naming restrictions, nothing special is required for a Python file
+to be a module, but the import mechanism needs to be understood in order to use
+this concept properly and avoid some issues.
 
 Concretely, the `import modu` statement will look for the proper file, which is
 `modu.py` in the same directory as the caller if it exists.  If it is not
