John Ousterhout

Simplify Code

Focus on making your code more obvious and eliminating special cases. This can be achieved by using consistent identifiers and avoiding unnecessary complexity.

Embrace Modular Design

Break down your software system into independent modules with clear interfaces and implementations. This minimizes dependencies and makes the system easier to manage and evolve.

Use Context Objects

Instead of passing variables through multiple methods, store them in a context object that can be accessed by all relevant methods. This reduces the complexity of your code and makes it easier to manage global state.

Measure System Performance Before Optimization

Before making any changes to improve performance, measure the system's existing behavior to identify the specific areas where tuning will have the most significant impact. This helps in avoiding unnecessary complexity and ensures that any optimizations are based on concrete data.

Document Each Design Decision Once

Avoid duplicating documentation. Instead, document each design decision exactly once in the most obvious place, and use references to point to this central location. This approach reduces the risk of inconsistencies and makes it easier for developers to find accurate information.

Write Comments First

Start by writing comments before you write the actual code. This helps in capturing the key design issues early and ensures that your documentation is thorough and accurate.

Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system.

The greatest limitation in writing software is our ability to understand the systems we are creating.

Good development tools can help us deal with complexity, but there is a limit to what we can do with tools alone.

Software design is a continuous process that spans the entire lifecycle of a software system.

Reducing complexity is the most important element of software design.

Special cases should be eliminated wherever possible.

When something is important, it must be exposed.

No one is good enough to get it right with their first try.

The guiding principle for comments is that comments should describe things that aren’t obvious from the code.

If the information in a comment is already obvious from the code next to the comment, then the comment isn’t helpful.

A good higher-level comment expresses one or a few simple ideas that provide a conceptual framework.

The best modules are those whose interfaces are much simpler than their implementations.

A deep module is a good abstraction because only a small fraction of its internal complexity is visible to its users.

The best way to ensure that comments get updated is to position them close to the code they describe, so developers will see them when they change the code.

Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use the same approach.

Managing Complexity

John Ousterhout emphasizes that the primary challenge in software design is managing complexity. He defines complexity as 'anything related to the structure of a software system that makes it hard to understand and modify the system.' This complexity inevitably increases over time, making it crucial for developers to adopt strategies to manage and reduce it. Ousterhout argues that the most significant limitation in writing software is our ability to understand the systems we create. As systems evolve and acquire more features, they become more complicated, leading to slower development and more bugs. He suggests that good development tools can help manage complexity, but ultimately, simpler designs are necessary to build more powerful systems before complexity becomes overwhelming.

Deep vs. Shallow Modules

Ousterhout introduces the concept of 'deep' and 'shallow' modules. Deep modules provide powerful functionality through simple interfaces, effectively hiding significant implementation complexity. For example, the Unix file I/O system, with its five basic system calls, is a deep module because it offers extensive functionality while keeping the interface simple. In contrast, shallow modules have complex interfaces relative to the functionality they provide, adding little value in managing complexity. Ousterhout criticizes the tendency to create numerous small, shallow classes and methods, a practice he terms 'classitis.' This approach increases overall system complexity by introducing many interfaces that developers must learn and manage.

Information Hiding

The concept of information hiding is central to creating deep modules in software design. Ousterhout emphasizes that each module should encapsulate specific pieces of knowledge, which represent design decisions. This knowledge is embedded within the module’s implementation but does not appear in its interface, making it invisible to other modules. For instance, the details of how to store information in a B-tree or how to implement the TCP network protocol are hidden within their respective modules. This approach simplifies the interface, reducing the cognitive load on developers who use the module. Ousterhout states, 'The interface reflects a simpler, more abstract view of the module’s functionality and hides the details; this reduces the cognitive load on developers who use the module.'

General-Purpose APIs

One of the central ideas in the book is the advantage of designing general-purpose APIs over specialized ones. Ousterhout argues that while it might seem intuitive to tailor APIs to specific needs, this approach often results in a high cognitive load for developers and a proliferation of shallow methods. For instance, in a text editor project, students created methods like `void backspace(Cursor cursor)` and `void delete(Cursor cursor)` to handle specific user interface actions. However, this specialization led to a large number of methods that were only useful for single operations, increasing complexity and information leakage between the user interface and text classes. Ousterhout suggests a more general approach, such as using methods like `void insert(Position position, String newText)` and `void delete(Position start, Position end)`, which simplifies the API and makes it more versatile.

Reducing Exception Complexity

Ousterhout suggests several strategies to mitigate the complexity introduced by exceptions. One key approach is to 'define errors out of existence.' By designing APIs in a way that eliminates the need for exceptions, developers can simplify their code. For example, he critiques the design of the `unset` command in Tcl, which throws an error if the variable does not exist. Instead, he proposes that `unset` should simply ensure that a variable no longer exists, thus avoiding unnecessary exceptions. This principle is further illustrated with the example of file deletion in Unix, where the system marks a file for deletion rather than throwing an error if the file is in use, thereby simplifying the user experience.

Precise Naming and Consistency

Ousterhout argues that vague names for variables and methods can lead to confusion and errors. For instance, he critiques the use of generic names like `x` and `y` for variables that could represent anything from coordinates to indices. Instead, he advocates for more descriptive names such as `charIndex` and `lineIndex`, which clearly convey their purpose. This practice not only makes the code more readable but also reduces the likelihood of misuse. Ousterhout emphasizes, 'The code would be clearer if it used names such as charIndex and lineIndex, which reflect the specific abstractions that the code implements.' Consistency in naming conventions is also crucial, as it reduces cognitive load and helps maintain a clean and understandable codebase.

Balancing Efficiency and Complexity

Ousterhout emphasizes that while optimizing for efficiency is important, it should not come at the cost of adding significant complexity to the system. He advises that if a more efficient design only adds a small amount of complexity and this complexity is hidden from interfaces, it might be worthwhile. However, if the efficient design results in complicated interfaces or a lot of implementation complexity, it is better to start with a simpler approach and optimize later if performance becomes an issue. This principle is illustrated with the example of the RAMCloud project, where the team decided to use special hardware for networking to achieve low latency, despite the added complexity, because kernel-based networking was too slow to meet their needs.

Automate Configuration

Avoid relying on configuration parameters whenever possible. Instead, implement mechanisms that automatically determine the best values for these parameters based on the system's operating conditions. This reduces the burden on users and ensures that the system adapts to changing conditions dynamically.

The best modules have simple interfaces which abstract away complex implementations.

Complexity is anything related tothe structure of a software system that makes ithard to understand and modify the system.

When choosing a name, try to capture the essential purpose of the entity being named using as few words as possible. Generic names are not recommended in most cases because it increases the chances that the named entity will be misused. It’s also important to be consistent when using names, so that the same name means the same thing throughout the codebase regardless of the context in which it was used.

Write comments when writing the code. Putting it off until later increases the chances that it doesn’t get written at all.

Complexity manifests itself in a software in 3 major ways ordered in terms of increasing severity:1. When a simple change requires modifying code in many places.2. When developers need to carry a lot of information in their heads to complete a task.3. When it is not obvious what information or changes are needed in order to carry out a task.

Favour deep modules over shallow onesDeep modules are those that provide simple interfaces to complex functionality, while shallow ones are those that have a complicated interface without hiding much complexity. Shallow modules add complexity to a system because of the cost of learning and using their interfaces, but without providing a compensating benefit by hiding complicated implementation details.

Place comments in the place where developers are most likely to see it (usually right next to the relevant code).

When documenting implementation details, focus on the what and why of the code. The how can be deduced by reading the code itself.

Use TDD when fixing bugs that can be reproduced using a test beforehand, so that the test can confirm that the bug was actually fixed after the necessary changes have been made.

A strategic programmer recognizes that “working code” is not a good enough standard if long-term maintainability is a paramount concern. Instead of trying to ship something as quickly as possible, this mindset encourages taking some time to find the best design that also happens to work.

TDD encourages tactical programming through its emphasis on getting specific features working instead of finding the right design, which is better achieved by considering the units of development as abstractions instead of features.

Exception handling as one of the worst sources of complexity in software systems. This is because exceptions increases the complexity of a module because it becomes part of the module’s interface causing users of the module to become aware of it, and increases the number of places where a potential exception must be handled.

Try to place yourself in the shoes of the reader, and ask yourself what they need to know about the entity being documented.

Comments should describe things that cannot be inferred from the code.

Obscurity — This occurs when some important information about the system is not obvious. For example, when it’s not clear what order in which to run a set of methods in order to carry out an operation. If code is not obvious, a reader must expend a lot of time and energy to attempt to understand it, and the likelihood of misunderstanding it is high.

The quality of names in a software system can affect its perceived complexity in non-trivial ways. Good names provide clarity by telling the reader what an entity is and what it is not, which reduces the need for extensive comments.

Use different words to describe the entity being documented to clarify its purpose. Focus on what the entity represents, and not on how it is manipulated.

Debunking the myths of commenting code - No time to write comments Taking the time to write comments is part of the investment mindset. To develop a software system that is easy to maintain, you have to spend some extra time doing the work to create that structure, and the benefits of having good documentation upfront will quickly offset any additional costs.

Interface comments (those that provide a high-level information on how to use a class or method) should not describe the implementation. Instead, document things like side effects, constraints on arguments, dependencies, exceptions or preconditions before a method is invoked.

Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system.

The greatest limitation in writing software is our ability to understand the systems we are creating.

Good development tools can help us deal with complexity, but there is a limit to what we can do with tools alone.

Software design is a continuous process that spans the entire lifecycle of a software system.

Reducing complexity is the most important element of software design.

Special cases should be eliminated wherever possible.

When something is important, it must be exposed.

No one is good enough to get it right with their first try.

The guiding principle for comments is that comments should describe things that aren’t obvious from the code.

If the information in a comment is already obvious from the code next to the comment, then the comment isn’t helpful.

A good higher-level comment expresses one or a few simple ideas that provide a conceptual framework.

The best modules are those whose interfaces are much simpler than their implementations.

A deep module is a good abstraction because only a small fraction of its internal complexity is visible to its users.

The best way to ensure that comments get updated is to position them close to the code they describe, so developers will see them when they change the code.

Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use the same approach.

Debunking the myths of commenting code - Good code is self-documenting: No matter how good the code is, it cannot capture the informal aspects of a module’s interface such as why a particular design decision was made, or the meaning of its result, hence the need for comments.

Dependencies — A dependency between two or more parts of a system is only desirable if the dependency is clear and obvious. When it is not clear what code depends on another, even simple changes to the system will take a long time and there would be a high risk of bugs showing up after deploying to production.

Debunking the myths of commenting code - Outdated comments become misleadingComments can sometimes get stale, but it shouldn’t be a huge effort to keep it up to date especially if comments are positioned next to the code they describe. Code reviews can also be effective at detecting and correcting outdated comments.