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.
Steve Jessop once took me to task over this issue.
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.
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;
}
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?
12
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 terms.
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” 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.
1
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:
jlear is a new contributor to this site. Take care in asking for clarification, commenting, and answering.
Check out our Code of Conduct.
1