src/arch_goals.md

   1 @page arch_goals High level code design practices
   2
   3 This page describes the high level design practices for Tor's code.
   4 This design is a long-term goal of what we want our code to look like,
   5 rather than a description of how it currently is.
   6
   7 Overall, we want various parts of tor's code to interact with each
   8 other through a small number of interfaces.
   9
  10 We want to avoid having "god objects" or "god modules".  These are
  11 objects or modules that know far too much about other parts of the
  12 code.  God objects/modules are generally recognized to be an
  13 antipattern of software design.
  14
  15 Historically, there have been modules in tor that have tended toward
  16 becoming god modules.  These include modules that help more
  17 specialized code communicate with the outside world: the configuration
  18 and control modules, for example.  Others are modules that deal with
  19 global state, initialization, or shutdown.
  20
  21 If a centralized module needs to invoke code in almost every other
  22 module in the system, it is better if it exports a small, general
  23 interface that other modules call.  The centralized module should not
  24 explicitly call out to all the modules that interact with it.
  25
  26 Instead, modules that interact with the centralized module should call
  27 registration interfaces.  These interfaces allow modules to register
  28 handlers for things like configuration parsing and control command
  29 execution.  (The config and control modules are examples of this.)
  30 Alternatively, registration can happen through statically initialized
  31 data structures.  (The subsystem mechanism is an example of this.)