The Missing README

3 Working with Code

There’s an ancient Roman amphitheater in Arles, France. It used to provide entertainment—chariot races and gladiatorial combat—for up to 20,000 people. After the fall of Rome, a small town was built right in the arena. This made sense; it had walls and a drainage system. Later inhabitants probably found the setup odd and inconvenient. They might have judged the architects of the amphitheater for choices that made it difficult to turn it into a town.

Codebases are like the amphitheater in Arles. Layers are written in one generation and modified later. Many people have touched the code. Tests are missing or enforce assumptions of a bygone era. Changing requirements have twisted the code’s usage. Working with code is hard. ...