Modular Design

Lecture Notes for CS 190
Winter 2018
John Ousterhout

Divide system into modules that are relatively independent
Ideal: each module completely independent of the others
- System complexity = complexity of worst module
In reality, modules are not completely independent
- Some modules must invoke facilities in other modules
- Design decisions in one module must sometimes be known to other modules
- Can't change one module without understanding parts of other modules
Divide each module into two parts:
- Interface: anything about the module that must be known to other modules
  - Formal aspects (in the code): method signatures, public variables, etc.
  - Informal aspects: overall behavior, side effects, constraints on usage, etc.
  - Informal aspects can only be described with comments
- Implementation: code that carries out the promises made by the interface
Goal: interface should be much simpler than the implementation
- If a change affects only a module's implementation, but not its interface, then it will not affect any other module

Abstraction

Deep class: small interface, lots of functionality
- Lots of information hidden
Example: Unix system calls for file I/O
Shallow class
- Complex interface and/or not much functionality
- Invoking a method isn't much easier than just typing in the code of the method.
- Shallow classes don't hide much information
- Example: linked list
- Also see User.java
- Every class and method introduces complexity with its interface
- Goal: get a lot of functionality for that complexity
- If a class is shallow, you have to spend a lot of time learning the interface, compared to how much time the class saves you.
Many courses teach students that "classes should be small": results in shallow classes.
Classitis: small classes taken to the extreme
- Each class adds the least possible amount of functionality to existing classes
- Bad example: Java libraries
Size doesn't really matter that much
- Classes in the range of 200-2000 lines are fine
- The most important thing is depth: the power of the abstraction
It's more important for a class to have a simple interface than a simple implementation

First proposed by David Parnas in a classic paper "On the Criteria To Be Used in Decomposing Systems into Modules"
- More than 40 years old, but still one of the most important papers in all of systems.
Each module (class) should encapsulate certain knowledge or design decisions:
The knowledge/design decisions are only known to the one module
The interface does not reflect this information (much)
Benefits:
- Simpler interface (deeper class)
- Can modify the implementation without impacting other classes
This is the single most important idea in software design; will revisit it over and over.
Information leakage: opposite of information hiding
- Implementation details exposed, other classes depend on them
- Anything in the interface is leaked
- Back-door leakage: not visible in the interface
Temporal decomposition: one of the most common causes of information leakage
- Code structure reflects the order in which operations execute
Using classes does not necessarily guarantee information hiding!
- Example: private variables can still be leaked
When you see information leakage, look for a way to bring all the information together in one place
Making classes a bit larger often creates opportunities for better information hiding

Questions to ask yourself:
- What is the unique value provided by this class (something this class does, but no other class)?
- What is the key knowledge that the class uses to provide that value?
- What's the least possible amount of that knowledge that must be exposed through the interface?

Should new classes be general-purpose or special-purpose?
- Special-purpose: just do exactly what's needed today
- General-purpose: solve a range of problems that may in the future
My advice: make classes somewhat generic:
- Overall capabilities reflect current needs
- Design an interface that is generic enough to be used for other purposes besides today's needs
- Result: simpler and deeper interface than special-purpose approach
Example from text editor project
Questions to ask yourself:
- What is the simplest API that will cover all of my current needs?
- In how many situations will this method be used?
- Is this API convenient to use for my current needs?

Each layer's abstraction should be different from the layer above it and the layer below it.
Red flag: pass-through methods
- Decide what's important, design the interface around that
  - Focus on the things that are done most frequently
  - Technique #1: if a particular task is invoked repeatedly, design an API around that task (even better, do it automatically, without having to be invoked).
  - Technique #2: if a collection of tasks are not identical, look for common features shared by all of them; design APIs for the common features.
  - It's OK to provide APIs for infrequently-used features, but design them in a way that you don't need to be aware of them when using the common features.
Bad example: Java I/O
Good example: device-independent I/O in UNIX/Linux:
- Before UNIX: different kernel calls for opening and accessing files vs. devices.
  - Different kernel calls for each device: terminal, tape, etc.
  - Different naming mechanisms for each device
- UNIX emphasized commonality across devices:
  - Devices have names in the file system: special device files
  - All devices have same basic access structure: open, read, write, seek, close
  - Handle device-specific operations with one additional kernel call:
```
int result = ioctl(int fd, int request,
        void* inBuffer, int inputSize,
        void* outBuffer, int outputSize);
```

How much to plan ahead?
- "Should I implement extra features beyond those that I need today?
- Design facilities that are general-purpose when possible (but don't get carried away)
- Don't create a lot of specific features that aren't needed now; you can always add them later.
- When you discover that new features or a more general architecture are needed, do it right away: don't hack around it.
The Martyr Principle
- Module writers should embrace suffering:
  - Take on hard problems
  - Solve completely
  - Make solution easy for others to use
  - Take more challenges for yourself, so that others have fewer issues to deal with
- Pull complexity down into modules:
  - Let a few module developers suffer, rather than thousands of users
  - Simple APIs are more important than a simple implementation
- Solve, don't punt:
  - Handle error conditions rather than throwing exceptions
  - Minimize "voodoo constants" (configuration parameters)
    - If you don't know the right value, how will a user or administrator ever figure it out?
Are long methods OK?
- Sometimes: see TransportDispatcher.cc (method consists of relatively independent pieces).
- Shorter is generally better, but only decompose if it can be done cleanly (are there dependencies between the parts?).
Applying These Ideas
- May be hard initially to apply these ideas when writing code.
- Make 2 designs and compare
- Pick one and write some code
- Watch for red flags
- Revise code
- Take advantage of code reviews