abstractions should be narrow but deep

From John Ousterhout in A Philosophy of Software Design, the ideal interface for a unit of code (e.g. module, function) is “narrow but deep”. In other words, it exposes maximal functionality through a minimal interface. He gives the counterexample of the Java file handling, which requires instantiating three different objects to open a file in the most common way:

FileInputStream fileStream = new FileInputStream(fileName);
BufferedInputStream bufferedStream = new BufferedInputStream(fileStream)
ObjectInputStream objectStream = new ObjectInputStream(bufferedStream())

Compare this with Ruby:

File.open(fileName)

Ousterhout’s point isn’t just about length, but abstraction—ideal APIs don’t minimize typing, they minimize thinking, at least thinking about things that don’t matter to the developer. Of course, what matters to the developer is contextual. But we can hide what doesn’t matter in the most common cases while providing lower-level abstractions as an escape hatch.