[tor-commits] [tor/master] Document high-level architecture goals

[nickm at torproject.org]

commit 0fd49c6663e3950092ec7436a43dc4154740df68
Author: Taylor Yu <catalyst at torproject.org>
Date:   Sun Dec 8 17:07:34 2019 -0600

    Document high-level architecture goals
    
    Create a high-level description of the long-term software architecture
    goals.  Closes ticket 32206.
---
 changes/ticket32206 |  3 +++
 src/arch_goals.md   | 31 +++++++++++++++++++++++++++++++
 src/mainpage.md     |  2 ++
 3 files changed, 36 insertions(+)

diff --git a/changes/ticket32206 b/changes/ticket32206
new file mode 100644
index 000000000..7ced81853
--- /dev/null
+++ b/changes/ticket32206
@@ -0,0 +1,3 @@
+  o Documentation:
+    - Create a high-level description of the long-term software
+      architecture goals.  Closes ticket 32206.
diff --git a/src/arch_goals.md b/src/arch_goals.md
new file mode 100644
index 000000000..92c86d9df
--- /dev/null
+++ b/src/arch_goals.md
@@ -0,0 +1,31 @@
+ at page arch_goals High level code design practices
+
+This page describes the high level design practices for Tor's code.
+This design is a long-term goal of what we want our code to look like,
+rather than a description of how it currently is.
+
+Overall, we want various parts of tor's code to interact with each
+other through a small number of interfaces.
+
+We want to avoid having "god objects" or "god modules".  These are
+objects or modules that know far too much about other parts of the
+code.  God objects/modules are generally recognized to be an
+antipattern of software design.
+
+Historically, there have been modules in tor that have tended toward
+becoming god modules.  These include modules that help more
+specialized code communicate with the outside world: the configuration
+and control modules, for example.  Others are modules that deal with
+global state, initialization, or shutdown.
+
+If a centralized module needs to invoke code in almost every other
+module in the system, it is better if it exports a small, general
+interface that other modules call.  The centralized module should not
+explicitly call out to all the modules that interact with it.
+
+Instead, modules that interact with the centralized module should call
+registration interfaces.  These interfaces allow modules to register
+handlers for things like configuration parsing and control command
+execution.  (The config and control modules are examples of this.)
+Alternatively, registration can happen through statically initialized
+data structures.  (The subsystem mechanism is an example of this.)
diff --git a/src/mainpage.md b/src/mainpage.md
index 3901e7955..8a7357881 100644
--- a/src/mainpage.md
+++ b/src/mainpage.md
@@ -29,6 +29,8 @@ Tor repository.
 
 @subpage intro
 
+ at subpage arch_goals
+
 @subpage initialization
 
 @subpage dataflow