A Philosophy of Software Design

by John Ousterhout

However, if you are having trouble figuring out what to do for the particular situation, there’s a good chance that the caller won’t know what to do either.

classes with lots of exceptions have complex interfaces, and they are shallower than classes with fewer exceptions.

define errors out of existence.

With this approach, an exceptional condition is detected and handled at a low level in the system, so that higher levels of software need not be aware of the condition.

Exception masking is an example of pulling complexity downward.

The third technique for reducing complexity related to exceptions is exception aggregation.

A single handler in this method can catch all of the exceptions and generate an appropriate error response for missing parameters.

However, getParameter knows nothing about the syntax of an HTTP error response.

Exception aggregation works best if an exception propagates several levels up the stack before it is handled;

masking usually works best if an exception is handled in a low-level method.

Design special cases out of existence

The notion of “no selection” makes sense in terms of how the user thinks about the application’s interface, but that doesn’t mean it has to be represented explicitly inside the application.

design it twice.

Does one alternative have a simpler interface than another? In the text example, all of the text interfaces are relatively simple.

Is one interface more general-purpose than another?

Does one interface enable a more efficient implementation than another? In the text example, the character-oriented approach is likely to be significantly slower than the others, because it requires a ...

Use the problems you identified with the original alternatives to drive the new design(s).

you might notice that each of the alternatives is awkward because it requires higher level software to perform additional text manipulations. That’s a red flag:

the process of writing comments, if done correctly, will actually improve a system’s design.

If you want to use abstractions to hide complexity, comments are essential.

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.

Change amplification: a seemingly simple change requires code modifications in many places.

Cognitive load: in order to make a change, the developer must accumulate a large amount of information.

Unknown unknowns: it is unclear what code needs to be modified, or what information must be considered in ord...

Comments Should Describe Things that Aren’t Obvious from the Code

comments should 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.

Interface:

Data structure member:

Implementation comment:

Cross-module comment:

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

use different words in the comment from those in the name of the entity being described.

Lower-level comments add precision

comments. Comments augment the code by providing information at a different level of detail.

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...

What are the units for this variable?

Are the boundary conditions inclusive or exclusive?

If a null value is permitted, what d...

If a variable refers to a resource that must eventually be freed or closed, who is responsibl...

Are there certain properties that are always true for the variable (invariants), such as “this list alway...

When documenting a variable, think nouns, not verbs.

Higher-level comments enhance intuition

Interface documentation

One of the most important roles for comments is to define abstractions.

If you want code that presents good abstractions, you must document those abstractions with comments.

interface comments from implementation comments.

Interface comments provide information that someone needs to know in order to use a class or method;

Implementation comments describe how a class or method works internally in order to i...