What is vertically coupled alignment in source code?

Question

Formatting multiline statements is an arcane art that most auto formatters and style guides can't help you with. One habit I picked up is to ensure renaming things wont cause multiple lines to need to move due to what I thought was called vertical coupling. However, when I go searching for this term Google is no help.

Example code:

Widget widget = WidgetBuilder.build()
                             .color("green")
                             .sprockets(13);

Note the dots are vertically coupled and depend on the first line. Anything gets renamed in the first line and the rest must move to preserve the vertical coupling.

However, this could have been laid out like so:

Widget widget = WidgetBuilder
    .build()
    .color("green")
    .sprockets(13)
;

This avoids the need to reposition following lines after a rename. Also avoids mixing tabs and spaces if you've been cursed with tabs.

This issue isn’t just about laying out builders. Here’s another example:

void MyClass::myFunction(const MyObject& obj,
                         const string& s1,
                         const string& s2,
                         const string& s3) {
    return;
}

Which could be laid out as:

void MyClass::myFunction(
        const MyObject& obj,
        const string& s1,
        const string& s2,
        const string& s3
) {
    return;
}

Steve Jessop once took me to task over this issue.

Does this concern have a better name? I could have sworn I saw this in a book once.

Anyway, is it better to avoid forcing people to adjust many lines just to rename something or better to leave it as it was?

Doc Brown · Accepted Answer · 2024-05-29T18:25:07.090

Note: at the time when I wrote this answer, the question title did not contain the term "alignment", only "vertical coupling".

I think most of us will agree there is no "perfect solution" to the described issue of readability vs. changing indentation in context of renaming, so let me focus on the answerable part of this question, the terminology.

What we see here are different kinds of multi-part statements, which we want to layout as multi-line blocks. This leads to the effect of vertically coupled alignment.

(I would not call this "vertical coupling", exactly for the reasons mentioned by Filip Milovanović in a comment: this term can be confused with it's meaning in regards to components and layers).

Now, there are two main kind of layout styles for multi-line blocks, both are described in Steve McConnell's classic book "Code complete (1st edition)" in chapter 18.3 ("Layout Styles"):

Endline Layout (as in the initial examples of the question)
Pure Blocks (as in the reformatted version of the examples)

When using "Endline Layout", the vertically coupled alignment leads to the necessity of changing indentation in case of renaming. Pure Blocks avoid this.

A little bit later in chapter 18.3, McConnell wrote:

In short, avoid endline layout because it's inaccurate, it's hard to apply consistently, and it's hard to maintain.

To be fair, at this point of the book, McConnell had blocks of multiple statements in mind, with some kind of begin/end brackets. Later, in chapter 18.5 ("Laying Out Individual Statements"), he presented different forms of indentation for routine-call continuation lines, either

by using standard indentation, or
by aligning under the first argument of the routine, or
by using one individual line per argument - including the first.

And to cite him finally about these layouts:

Any of the three options for formatting multiple-line routine calls works all right, if you use it consistently.

score 1 · Answer 2 · answered May 29 '24 at 12:17

Anyway, is it better to avoid forcing people to adjust many lines just to rename something or better to leave it as it was?

Neither. It's better to have a tool¹ enforce either (or neither) style, and not spend any thought on it yourself. The formatter configuration should be stored alongside the code, and preferably part of the integration process should enforce the formatting.

It doesn't have to be a single tool, if multiple can understand a shared configuration.

score -3 · Answer 3 · answered May 28 '24 at 22:10

You might search for Wrapping, Indentation, and Alignment. I use DevExpress' CodeRush to format my C# code, and these settings are under "Wrapping". Visual Studio also does a lighter version of this and it's under Indentation in the settings.

Here's an example CodeRush setting:

What is vertically coupled alignment in source code?

3 Answers3