Structured Indentation

A concept that makes source code easier to read.

Structured Indentation

Summary

Structured indentation (SI) is a concept that makes source code easier to read.

Sentences have structure, whether in human languages or in computer languages.

While the structure of human sentences is intuitively understood, understanding statements and expressions in computer languages takes significantly more effort. The structure is much stronger and carries much more meaning.

The problem

And yet, code is often formatted in ways that make this already complicated syntax even harder to understand.

Take, for example, this C++ code:

Display::Display(Keyboard &keyboard, int output, const Vector &position,
                 const Vector &size, const Vector &expandTo, Screen screen)
    : keyboard_(keyboard), output_{output}, screen_{screen},
      cursor_(enter(position)), terminalSize_{terminalSize()},
      foreground_{RgbWhite}, background_{RgbNone}, attributes_{},
      position_{screen == Screen::alternate? Vector{0, 0}
                : position == VectorMin    ? cursor_
                                            : position},
      maxSize_{min(expandTo == VectorMax? terminalSize_ : expandTo,
                   screen == Screen::alternate
                       ? terminalSize_
                       : Vector{toDim(terminalSize_.x() - position_.x()),
                                terminalSize_.y()})},
      text_(Null, size == VectorMin ? Vector{1, 1} : min(size, maxSize_)) {
  cursor(false);
  makeRoom(text_.height());
  keyboard.displayOffset(position_);
}

The formatting offers no visual hint of the structure hidden inside this constructor.

The solution

Compare it with this formatting:

Display::Display(
  Keyboard & keyboard,
  int output,
  const Vector & position,
  const Vector & size,
  const Vector & expandTo,
  Screen screen
):
  keyboard_(keyboard),
  output_{output},
  screen_{screen},
  cursor_(enter(position)),
  terminalSize_{terminalSize()},
  foreground_{RgbWhite},
  background_{RgbNone},
  attributes_{},
  position_{
    screen == Screen::alternate?
      Vector{0, 0}:
      position == VectorMin?
        cursor_:
        position
  },
  maxSize_{
    min(
      expandTo == VectorMax?
        terminalSize_:
        expandTo,
      screen == Screen::alternate?
        terminalSize_:
        Vector{toDim(terminalSize_.x() - position_.x()), terminalSize_.y()}
    )
  },
  text_(Null, size == VectorMin? Vector{1, 1}: min(size, maxSize_))
{
  cursor(false);
  makeRoom(text_.height());
  keyboard.displayOffset(position_);
}

The indentation makes the syntax hierarchy visible, and a simple principle achieves this:

  1. Every context that does not fit on a line opens with the token that opens it last on the line, followed by indentation.
  2. Every context that does not fit on a line closes with its dedented closing token.
  3. Contexts that use only a single token — an opening token without a closing token — are formatted the same way: indentation after the opening token, and dedentation after the context. This covers the : after the function notation and the ? in the ternary operator.
  4. Items in an indented block are preferably written below each other.

This creates a visual line that outlines a context’s contents, making its delimiters easy to spot.

After a closing token, the text can continue on the same line, as with the : after the function notation, provided the statement isn’t terminated by that token.

As long as those principles aren’t violated, source code becomes very easy to read.