A Philosophy of Software Design Quotes

“Almost every software development organization has at least one developer who takes tactical programming to the extreme: a tactical tornado. The tactical tornado is a prolific programmer who pumps out code far faster than others but works in a totally tactical fashion. When it comes to implementing a quick feature, nobody gets it done faster than the tactical tornado. In some organizations, management treats tactical tornadoes as heroes. However, tactical tornadoes leave behind a wake of destruction. They are rarely considered heroes by the engineers who must work with their code in the future. Typically, other engineers must clean up the messes left behind by the tactical tornado, which makes it appear that those engineers (who are the real heroes) are making slower progress than the tactical tornado.”
― John Ousterhout, A Philosophy of Software Design

“Your job as a developer is not just to create code that you can work with easily, but to create code that others can also work with easily.”
― John Ousterhout, A Philosophy of Software Design

“If your code is undergoing review and a reviewer tells you that something is not obvious, don’t argue with them; if a reader thinks it’s not obvious, then it’s not obvious. Instead of arguing, try to understand what they found confusing and see if you can clarify that, either with better comments or better code.”
― John Ousterhout, A Philosophy of Software Design

“Methods containing hundreds of lines of code are fine if they have a simple signature and are easy to read. These methods are deep (lots of functionality, simple interface), which is good.”
― John Ousterhout, A Philosophy of Software Design

“Most modules have more users than developers, so it is better for the developers to suffer than the users. As a module developer, you should strive to make life as easy as possible for the users of your module, even if that means extra work for you. Another way of expressing this idea is that it is more important for a module to have a simple interface than a simple implementation.”
― John Ousterhout, A Philosophy of Software Design

“If software developers should always be thinking about design issues, and reducing complexity is the most important element of software design, then software developers should always be thinking about complexity.”
― John Ousterhout, A Philosophy of Software Design

“One of the most important elements of software design is determining who needs to know what, and when.”
― John Ousterhout, A Philosophy of Software Design

“My current opinion is that an interface described in English is likely to be more intuitive and understandable for developers than one written in a formal specification language.”
― John Ousterhout, A Philosophy of Software Design

“Here are a few of of the most important red flags discussed in this book. The presence of any of these symptoms in a system suggests that there is a problem with the system’s design: Shallow Module: the interface for a class or method isn’t much simpler than its implementation (see pp. 25, 110). Information Leakage: a design decision is reflected in multiple modules (see p. 31). Temporal Decomposition: the code structure is based on the order in which operations are executed, not on information hiding (see p. 32). Overexposure: An API forces callers to be aware of rarely used features in order to use commonly used features (see p. 36). Pass-Through Method: a method does almost nothing except pass its arguments to another method with a similar signature (see p. 52). Repetition: a nontrivial piece of code is repeated over and over (see p. 68). Special-General Mixture: special-purpose code is not cleanly separated from general purpose code (see p. 71). Conjoined Methods: two methods have so many dependencies that its hard to understand the implementation of one without understanding the implementation of the other (see p. 75). Comment Repeats Code: all of the information in a comment is immediately obvious from the code next to the comment (see p. 104). Implementation Documentation Contaminates Interface: an interface comment describes implementation details not needed by users of the thing being documented (see p. 114). Vague Name: the name of a variable or method is so imprecise that it doesn’t convey much useful information (see p. 123). Hard to Pick Name: it is difficult to come up with a precise and intuitive name for an entity (see p. 125). Hard to Describe: in order to be complete, the documentation for a variable or method must be long. (see p. 133). Nonobvious Code: the behavior or meaning of a piece of code cannot be understood easily. (see p. 150).”
― John Ousterhout, A Philosophy of Software Design

“Here are the most important software design principles discussed in this book: Complexity is incremental: you have to sweat the small stuff (see p. 11). Working code isn’t enough (see p. 14). Make continual small investments to improve system design (see p. 15). Modules should be deep (see p. 23) Interfaces should be designed to make the most common usage as simple as possible (see p. 27). It’s more important for a module to have a simple interface than a simple implementation (see pp. 61, 74). General-purpose modules are deeper (see p. 39). Separate general-purpose and special-purpose code (see pp. 45, 68). Different layers should have different abstractions (see p. 51). Pull complexity downward (see p. 61). Define errors out of existence (see p. 81). Design it twice (see p. 91). Comments should describe things that are not obvious from the code (see p. 101). Software should be designed for ease of reading, not ease of writing (see p. 151). The increments of software development should be abstractions, not features (see p. 156). Separate what matters from what doesn’t matter and emphasize the things that matter (see p. 171”
― John Ousterhout, A Philosophy of Software Design

“Dealing with complexity is the most important challenge in software design. It is what makes systems hard to build and maintain, and it often makes them slow as well.”
― John Ousterhout, A Philosophy of Software Design

“In general, simpler code tends to run faster than complex code. If you have defined away special cases and exceptions, then no code is needed to check for those cases and the system runs faster. Deep classes are more efficient than shallow ones, because they get more work done for each method call. Shallow classes result in more layer crossings, and each layer crossing adds overhead.”
― John Ousterhout, A Philosophy of Software Design

“not only does simplicity improve a system’s design, but it usually makes systems faster.”
― John Ousterhout, A Philosophy of Software Design

“It used to be that developers rarely wrote tests. If tests were written at all, they were written by a separate QA team. However, one of the tenets of agile development is that testing should be tightly integrated with development, and programmers should write tests for their own code. This practice has now become widespread.”
― John Ousterhout, A Philosophy of Software Design

“it isn’t possible to visualize a complex system well enough at the outset of a project to determine the best design. The best way to end up with a good design is to develop a system in increments, where each increment adds a few new abstractions and refactors existing abstractions based on experience.”
― John Ousterhout, A Philosophy of Software Design

“One of the most important elements of agile development is the notion that development should be incremental and iterative. In the agile approach, a software system is developed in a series of iterations, each of which adds and evaluates a few new features; each iteration includes design, test, and customer input.”
― John Ousterhout, A Philosophy of Software Design

“Agile development is an approach to software development that emerged in the late 1990’s from a collection of ideas about how to make software development more lightweight, flexible, and incremental; it was formally defined during a meeting of practitioners in 2001.”
― John Ousterhout, A Philosophy of Software Design

“If code is obvious, a reader doesn’t need to spend much time or effort to gather all the information they need to work with the code. If code is not obvious, then a reader must expend a lot of time and energy to understand it. Not only does this reduce their efficiency, but it also increases the likelihood of misunderstanding and bugs. Obvious code needs fewer comments than nonobvious code.”
― John Ousterhout, A Philosophy of Software Design

“Don’t change existing conventions. Resist the urge to “improve” on existing conventions. Having a “better idea” is not a sufficient excuse to introduce inconsistencies. Your new idea may indeed be better, but the value of consistency over inconsistency is almost always greater than the value of one approach over another.”
― John Ousterhout, A Philosophy of Software Design

“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. If a system is not implemented in a consistent fashion, developers must learn about each situation separately. This will take more time.”
― John Ousterhout, A Philosophy of Software Design

“If you want to maintain a clean design for a system, you must take a strategic approach when modifying existing code. Ideally, when you have finished with each change, the system will have the structure it would have had if you had designed it from the start with that change in mind. To achieve this goal, you must resist the temptation to make a quick fix.”
― John Ousterhout, A Philosophy of Software Design

“Writing the comments first makes documentation part of the design process. Not only does this produce better documentation, but it also produces better designs and it makes the process of writing documentation more enjoyable.”
― John Ousterhout, A Philosophy of Software Design

“Selecting names for variables, methods, and other entities is one of the most underrated aspects of software design. Good names are a form of documentation: they make code easier to understand. They reduce the need for other documentation and make it easier to detect errors. Conversely, poor name choices increase the complexity of code and create ambiguities and misunderstandings that can result in bugs.”
― John Ousterhout, A Philosophy of Software Design

“When writing comments, try to put yourself in the mindset of the reader and ask yourself what are the key things he or she will need to know.”
― John Ousterhout, A Philosophy of Software Design

“Comments augment the code by providing information at a different level of detail. Some comments provide information at a lower, more detailed, level than the code; these comments add precision by clarifying the exact meaning of the code. Other comments provide information at a higher, more abstract, level than the code; these comments offer intuition, such as the reasoning behind the code, or a simpler and more abstract way of thinking about the code.”
― John Ousterhout, A Philosophy of Software Design

“Developers should be able to understand the abstraction provided by a module without reading any code other than its externally visible declarations.”
― John Ousterhout, A Philosophy of Software Design

“The overall idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in the code.”
― John Ousterhout, A Philosophy of Software Design

“Some people believe that if code is written well, it is so obvious that no comments are needed. This is a delicious myth, like a rumor that ice cream is good for your health: we’d really like to believe it! Unfortunately, it’s simply not true.”
― John Ousterhout, A Philosophy of Software Design

“Inadequate documentation creates a huge and unnecessary drag on software development.”
― John Ousterhout, A Philosophy of Software Design

“In-code documentation plays a crucial role in software design. Comments are essential to help developers understand a system and work efficiently, but the role of comments goes beyond this. Documentation also plays an important role in abstraction; without comments, you can’t hide complexity.”
― John Ousterhout, A Philosophy of Software Design