Added note about GUI architecture to doc/hacking.txt + doc/img/gui_flow/.

[hooke.git] / doc / hacking.txt

diff --git a/doc/hacking.txt b/doc/hacking.txt
index 62919e110820c56409c0e83e768c548748e20e49..c0e954da0f404781d264c4971865f0488a3f0992 100644 (file)
--- a/doc/hacking.txt
+++ b/doc/hacking.txt
@@ -1,11 +1,11 @@
-*************
-Hacking Hooke
-*************
+*******
+Hacking
+*******
 
 .. toctree::
    :maxdepth: 2
 
-   testing.txt
+   testing
 
 Dependencies
 ============
@@ -31,10 +31,24 @@ standard library, we use configparser_ for the config files.
 
 On the testing side, the need to stick to the standard library relaxes
 (developers can install extra packages), so we can use nose_.  See
-the Testing_ section for more information.
+the :doc:`testing` section for more information.
 
 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.3/
-.. _Testing: testing.txt
+
+
+Principles
+==========
+
+Hooke aims to be easily modified and extended by new recruits.  To
+make this easier, we try to abide by several programming practices.
+
+* `DRY`_ (Don't Repeat Yourself), also phrased as "Every piece of
+  knowledge must have a single, unambiguous, authoritative
+  representation within a system."
+* `LoD`_ (Law of Demeter): Don't reach through layers, e.g. `a.b.c.d()`.
+
+.. _DRY: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+.. _LoD: http://en.wikipedia.org/wiki/Law_of_Demeter
 
 
 Architecture
@@ -133,3 +147,19 @@ There are also a number of features who's standard library support
 changes with different versions of Python.  :mod:`~hooke.compat`
 provides a uniform interface to those tools so that Hooke will work
 with several Python versions.
+
+GUI
+---
+
+:mod:`hooke.ui.gui` contains enough code that you might want a word
+about its organization before diving into the code.  Information flows
+like this:
+
+.. image:: img/gui_flow/gui_flow.svg
+  
+With the following naming scheme in HookeFrame:
+
+  ===================  ==================
+  callbacks            ``_on_*``
+  response processors  ``_postprocess_*``
+  ===================  ==================