Simon Smart argues that modern code is harder to understand than code from any previous era. Not because it is badly written — because decoupling replaced “spaghetti code” with “ravioli code”: components that are individually tidy and act autonomously, with no visible thread connecting them.

The cost lands on anyone who has to navigate it:

  • With spaghetti there were at least strands to follow. With pub/sub, it can be extremely difficult to say what a piece of code does or what caused it to execute.
  • The default behaviour is to charge into the maze, run around until you hit the right place, then leave — and do it all again next time.
  • “In most cases, we spend much more time trying to understand the code than we ever do making changes to it.”

He is careful not to turn this into an architecture argument — choosing how code is shaped is “very much a luxury” for most developers. Everyone else just has to find their way through what they inherited. So the leverage is in leaving navigation aids.

Signposts (comments)

  • A mix of inline and standalone comments, depending on the case.
  • Usually keep comments to one line: if it is useful, developers will scroll; if not, they scroll past.
  • No comments with no value — nobody needs X + 1 explained.
  • Explain why most of the time, but not always — sometimes the what is the part that needs stating.
  • Be explicit and complete rather than brief.
  • Signposts should show where you came from and where you are going, not just how the code works. Explaining how execution reaches a line is often the most valuable part.
  • If someone asks a question in code review, that is a signal a comment is missing.

Maps (documentation)

  • Put docs somewhere public that everyone can reach.
  • Diagrams are high-value maps — Mermaid and draw.io are the author’s choices.
  • Document the parts developers work in most, not everything.
  • A few paragraphs on an obscure subsystem beats hundreds of pages of nothing.
  • Link from docs into the code, and from comments back into docs.
  • Be explicit; if outside context is needed, link to the document that carries it.
  • Use headings, bold, italics and consistent colours (always yellow for an INSERT, say) so readers build intuition without reading every word.

The pushback on comments usually cites maintenance cost and the idea that comments let people write unintuitive code. This essay’s counter is that in maze-shaped systems signposts matter more than they used to, not less — and the return on a map shows up as time saved in someone else’s future debugging session.

A tattered old map is still much better than no map at all.