A philosophy of software design - John Ousterhout

When building software systems, the core challenge is managing complexity. Complexity makes it more difficult for a programmer to understand and change software, it increases the rate of errors, it slows development velocity, and has other negative affects.

Software design is one of the key tools for managing complexity. Ousterhout discusses the different types and causes of complexity, and then various software design considerations and their relationship to complexity - patterns, antipatterns, questions to ask, etc.

Ultimately, complexity makes it more expensive to modify a program: changes are more difficult, take longer, and are more likely to introduce errors to a program.

Ousterhout identifies three general ways that complexity manifests itself:

1. Change amplification: where a seemingly simple change requires code modifications in many different places.
2. Cognitive load: where a developer needs to know a large number of things in order to complete a task.
3. Unknown unknowns: where it's unclear what to do, or whether a proposed solution will even work.

The overall complexity of a system can be determined by the complexity of each part, weighted by the fraction of time developers spend working on that part. If you isolate complexity in a place where it will never be seen, then that's almost as good as eliminating it entirely.

Ousterhout recognises two main causes of complexity.

1. Dependencies between software components, which can lead to change amplification and a high cognitive load. Dependencies are a fundamental part of software and can't be eliminated, but one of the goals of software design is to eliminate dependencies where possible, and to make the dependencies that remain as simple and obvious as possible.
2. Obscurity - when important information is not obvious. This creates unknown unknowns, and also contributes to cognitive load.

Ousterhout advocates for a strategic approach to software development, rather than a wholly tactical approach. This essentially just means ongoing, regular investment of some of your development time towards system design, rather than just working code.

One pitfall is that complexity in software development is incremental. A single shortcut or tactical decision that adds complexity won't have much impact, but small decisions can accumulate to dozens or hundreds of things that do have an impact. Then refactoring becomes a big task that you can't easily schedule with the business, so you look for quick patches, and this creates yet more complexity, which requires more patches, and so forth.

Once a codebase gets complex enough, it is nearly impossible to fix, and you will probably pay high development costs for the rest of its life.

If someone says your code is not obvious, then it isn't. This is stated a few times through the book.

This is one of the core themes in the book. A software system is usually decomposed into a collection of modules that are relatively independent. Modules inevitably have dependencies between them - they work together by calling each other, and therefore must know about each other. In order to manage these dependencies, we think about a module in two parts: an interface (what the module does), and an implementation (how it does it).

The idea of abstraction is closely related to modules. An abstraction is a simplified view of an entity which omits unimportant details, making it easier for us to think about and manipulate complex things.

Ousterhout argues that the best modules are those that provide powerful functionality, but have a simple interface. He describes these as deep modules, in contrast to shallow modules, which have a complex interface but not much functionality, thereby not hiding significant complexity.

The file I/O interface provided by Unix is a good example of a deep interface - the API only has a few system calls (open, read, write, seek, close), but hides a huge amount of complexity around implementation of files, directories, permissions, concurrent access, etc.

This doesn't mean "generalised" implementations that support extra features that you don't need - it means writing methods that are not overly specialised. The sweet spot is a somewhat general-purpose approach, which hopefully provides a simpler and deeper interface.

"If you reduce the number of methods in an API without reducing its overall capabilities, then you are probably creating more general-purpose methods."

Pass-through variables add complexity because they force intermediate methods to be aware of their existence, even though the methods have no use for the variables.

Eliminating this anti-pattern can be very difficult. The two main approaches are to see if you can add the pass-through state onto an object that is already shared between the top and bottom methods, or to make it a global variable. These can have their own problems.

Ousterhout's most often-used approach to this problem is to introduce a context object, which stores the application's global state - anything that would otherwise be a pass-through or global variable. They are not an ideal solution because they have a lot of the disadvantages of global variables, but they can reduce the complexity of a method's signature.

A pass-through method is one that does little except invoke another method with a similar signature. This increases the interface complexity of a module, without increasing the total functionality of the system. It can indicate that there is confusion over the division of responsibility between modules or classes.

This is not always bad - the important thing is that each new method should contribute significant functionality. For example, a dispatcher method is a pass-through method that can be very useful.

Decorators are often shallow pass-through methods that add a lot of boilerplate without adding much new functionality.

It's more important for a module to have a simple interface than a simple implementation. If you have complexity that is closely related to your module's functionality, you should consider pulling that complexity into the module's implementation.

One example Ousterhout provides is configuration parameters, which are an example of moving complexity upwards rather than down. Consider a network protocol that has to deal with lost packets: one way to determine an appropriate retry interval is to introduce a configuration parameter to provide control to the user. However, it may be preferable to compute a reasonable retry value automatically during runtime (by eg. measuring the response time). This approach pulls system complexity downwards.

"Exception handling is one of the worst sources of complexity in software systems". They can leak abstraction details upwards, making for a more shallow abstraction. Programmers are often taught that they need to handle exceptional cases, leading for an over-defensive programming style.

There are two main ways to handle exceptions, each with their own complexity. The first is to complete the work in spite of the exception, and the second is to report the exception upwards (perhaps also running some unwinding / handling logic).

Ousterhout argues in favour of defining errors out of existence, by automatically handling certain cases. He contrasts the behaviour of deleting a file on Windows vs Unix. On Windows, if a process is using the file to be deleted, an error is raised. In the Unix implementation, if another process is using the file, the file is internally marked for deletion and the operation returns successfully. Unix actually deletes the file when the other process has finished using it. Errors are avoided in both the process that initiated the deletion, and the other process that was using the file. Another common example is when accessing a substring by index: you could raise an out of bounds error, or you could just return the whole string.

Where you must handle exceptions, you should prefer to handle many exceptions with a single piece of code.

Ousterhout shares a few opinions on comments:

• A programming language can't capture all of the important information that was in the mind of the developer when the code was written. Comments should be used to describe things that aren't obvious from the code.
• "Developers should be able to understand the abstraction provided by a module without reading any code other than its externally visible declarations." If you want code that presents good abstractions, you must document those abstractions with comments.
• Write comments early, because they can help to improve the system design. Comments are likely to be low-quality if you write them as a token gesture at the end of a piece of work.
• Comments can indicate complexity: if a method or variable describes a long comment, it is a red flag that you don't have a good abstraction.
• Comments should not repeat the code. Could somebody who has never seen the code write your comment just by looking at the code? If so, the comment is worthless.
• Comments should be written at a different level of detail to the code - either higher (eg. concerned with top-level behaviour), or lower (concerned with specific details that are not obvious by reading the code). Comments are easier to maintain if they are higher-level and more abstract than the code. This is because they're less likely to be affected by minor changes in the code.
• Comments should occur close to the code that they describe. This increases the ease of reading and updating them. It's more important that comments are in the code, than in the commit log. This is because it's significantly easier to find the comments if they're close to the code - finding the right log message is difficult.
• Try to document each design decision exactly once. If information is already documented outside your program, don't repeat the documentation inside the program, just reference the external documentation.

Good names are a form of documentation, and another place where all programmers have seen incremental complexity: a single bad name does not hurt a program, but a program full of poorly-named components can be very difficult to use.

Names should be precise (you usually want to avoid overly-general names like data), and consistent - if a name is used in multiple places it should refer to the same thing. If the same name is used to refer to different concepts, then at some point a reader will be confused, which is likely to introduce errors to the program.

One way to make code more obvious to the reader is to have blank lines between parts that are logically separate, and maybe to preface the code block with an implementation comment.

"The problem with test-driven development is that it focuses on getting specific features working, rather than finding the best design." Ousterhout argues that the unit of development should be abstractions rather than features, and that once you discover the need for an abstraction, you should design it all at once.

He says that TDD does make sense when fixing bugs (which aligns with my experience).

Consistency minimises complexity because it provides cognitive leverage: you learn how something is done in one place, and you can immediately understand other places that use the same approach. If a system is not implemented consistently, then developers must learn about each situation separately, which takes more time.

Consistency also reduces mistake: if a system is not consistent, two situations that appear the same may actually be different.

Consistency can be considered in things like:

• Naming.
• Coding style.
• Interfaces.
• Design patterns.
• Invariants - cases that are always true. For example, a data structure storing lines of text might enforce an invariant that each line is terminated by a newline character. The programmer can then always assume this to be true.

There are things you can do to ensure consistency:

• Write conventions down.
• Enforce conventions, ideally automatically through tools.
• "When in Rome…" follow existing conventions. Having a better idea is not a sufficient excuse to introduce inconsistencies. Is your new approach so much better that it's worth taking the time to update all of the old uses?

Implementation inheritance creates dependencies between the parent class and each of its subclasses, results in information leakage between the parent and child classes, and makes it hard to modify one class in the hierarchy without looking at the other.

Ousterhout suggests composition can be a less-complex alternative to inheritance.

The first example that jumps to mind personally is Django - the class hierarchy always seemed to add more complexity than it solved in a lot of cases. In general I think it's very easy for the complexity of inheritance to outweigh the utility.

Event-driven programming makes it hard to follow the flow of control. This is because handler functions aren't invoked directly - it depends on which handlers were registered at runtime.

This doesn't mean that there is no use-case for event-driven programming, but care should be taken to mitigate this complexity.

You'll end up with a much better result if you consider multiple options for each major design decision. There isn't much to say about this, other than that I intuitively agree.