A Philosophy of Software Design

by John Ousterhout

If information is already documented someplace outside your program, don’t repeat the documentation inside the program; just reference the external documentation.

comments are easier to maintain if they are higher-level and more abstract than the code.

Consistency is a powerful tool for reducing the complexity of a system and making its behavior more obvious.

Consistency creates cognitive leverage:

Names.

Coding style.

Interfaces.

Design patterns are generally-accepted solutions to certain common problems,

Invariants reduce the number of special cases that must be considered in code and make it easier to reason about the code’s behavior.

Create a document that lists the most important overall conventions, such as coding style guidelines.

The best way to enforce conventions is to write a tool that checks for violations, and make sure that code cannot be committed to the repository unless it passes the checker.

Don’t change existing conventions.

Having a “better idea” is not a sufficient excuse to introduce inconsistencies.

Obscurity occurs when important information about a system is not obvious to new developers.

The first is choosing good names

Precise and meaningful names clarify the behavior of the code and reduce the need for documentation.

The second technique is consistency

Judicious use of white space.

If the meaning and behavior of code cannot be understood with a quick reading, it is a red flag. Often this means that there is important information that is not immediately clear to someone reading the code.

Generic containers.

rule: software should be designed for ease of reading, not ease of writing.

Different types for declaration and allocation.

To make code obvious, you must ensure that readers always have the information they need to understand it.

In order for an interface to have many implementations, it must capture the essential features of all the underlying implementations while steering clear of the details that differ between the implementations; this notion is at the heart of abstraction.

development should be incremental and iterative. In the agile approach, a software system is developed in a series of iterations,

Developing incrementally is generally a good idea, but the increments of development should be abstractions, not features.

The problem with test-driven development is that it focuses attention on getting specific features working, rather than finding the best design.

Before fixing a bug, write a unit test that fails because of the bug. Then fix the bug and make sure that the unit test now passes.

such as an iterator or an observer.

Design patterns represent an alternative to design: rather than designing a new mechanism from scratch, just apply a well-known design pattern.

The greatest risk with design patterns is over-application.

Network communication: even within a datacenter, a round-trip message exchange can take 10–50 µs, which is tens of thousands of instruction times. Wide-area round-trips can take 10–100 ms.

I/O to secondary storage: disk I/O operations typically take 5–10 ms,

Design around the critical path

The most important overall lesson from this chapter is that clean design and high performance are compatible.

This book is about one thing: complexity.

how can a particular problem be solved with the simplest possible structure?

Complexity is incremental: you have to sweat the small stuff (see p. 11).

Working code isn’t enough (see

Make continual small investments to improve sy...

Modules should...

Interfaces should be designed to make the most common usage as simpl...

It’s more important for a module to have a simple interface than a ...

General-purpose modules are deeper

Separate general-purpose and special-purpose code

Different layers should have differen...

Pull complexity ...

Define errors (and special cases) out...

Design it twi...

Comments should describe things that are not obvi...