diff options
| author | Taylor Yu <catalyst@torproject.org> | 2019-12-08 17:07:34 -0600 |
|---|---|---|
| committer | Taylor Yu <catalyst@torproject.org> | 2019-12-10 16:47:38 -0600 |
| commit | 0fd49c6663e3950092ec7436a43dc4154740df68 (patch) | |
| tree | 782d26ddd1b0f33bd51de93bdcd5fdb2c26008e8 | |
| parent | 089466eff356454b0e0eb4e1d432057504a9a4d6 (diff) | |
| download | tor-0fd49c6663e3950092ec7436a43dc4154740df68.tar.gz tor-0fd49c6663e3950092ec7436a43dc4154740df68.zip | |
Document high-level architecture goals
Create a high-level description of the long-term software architecture
goals. Closes ticket 32206.
| -rw-r--r-- | changes/ticket32206 | 3 | ||||
| -rw-r--r-- | src/arch_goals.md | 31 | ||||
| -rw-r--r-- | src/mainpage.md | 2 |
3 files changed, 36 insertions, 0 deletions
diff --git a/changes/ticket32206 b/changes/ticket32206 new file mode 100644 index 0000000000..7ced81853e --- /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 0000000000..92c86d9df8 --- /dev/null +++ b/src/arch_goals.md @@ -0,0 +1,31 @@ +@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 3901e79559..8a73578819 100644 --- a/src/mainpage.md +++ b/src/mainpage.md @@ -29,6 +29,8 @@ Tor repository. @subpage intro +@subpage arch_goals + @subpage initialization @subpage dataflow |