Why Aligning Statements Will Haunt You

fagnerbrack.com 4 min read Original

Summary

Aligning statements with spaces, like lining up require statements or object literal properties, creates unnecessary version control changes. Adding one new dependency forces you to realign all existing lines, so a one-line addition becomes two lines removed and three added in the diff. This breaks atomic commits and pollutes git blame with commits that touch unrelated lines.

The problem goes beyond diffs. Alignment raises the chance of merge conflicts when someone commits to an aligned block while you have local changes, even if you never touched the same line. Conflicts can also appear when reverting, rebasing, merging, or cherry-picking, since branches may use different alignment. Putting alignment fixes in a separate commit or pull request does not solve it.

Alignment also gives a false sense of organization. Skip it and you get consistency by default. Use it and you must document the rule and trust everyone to follow it, or the Broken Window Theory kicks in and the code drifts. The same issue applies to any aligned code, not just node require statements.

Why Aligning Statements Will Haunt You

Shaggy and Scooby, looking at the screen. Frightened.

For example, let's see this pattern that is know to have been used over and over again in a few node based applications:

A code example showing two lines with require statements aligned with spaces before the "equals" sign

The idea is to keep the require statements aligned. This supposedly makes your code easier to read.

Seems harmless, right? And it is. As long as you are working on a project alone and don't care about your version control system.

What happens if you need to add in the future a new dependency to your file, like the example below?

A code example showing the same require statements with an additional one in the bottom. The last variable has a name bigger than the others.

The logged changes in the version control system will look like this (1 line added):

A diff showing the same require statements with the last line added

But wait a second, you need to "fix" the alignment for consistency. So now your logged changes in the version control system will look like this (2 lines removed, 3 lines added):

A diff showing all other require statements as lines removed and the last statement (including the other ones) as lines added

We should always be careful to write code that actually changes what we intend to do. Changing all those lines was definitely not the intention. In git, when inspecting the git blame later to look for the root cause of a problem, we will have lines with commits that contain unrelated changes to them. That breaks the whole purpose of only logging relevant changes on each line so that it can be efficiently trackable.

Code alignment introduces to the version control system changes that are irrelevant to the lines that were changed

We have introduced useless changes, and with it, we have also introduced an unnecessary focus in the diff for those who are going to review it.

Of course, your diff tool might figure out the small change and highlight less code, or allow ignoring whitespace changes altogether (like git diff — ignore-space-change and git merge -Xignore-space-change or Github's ?w=1). But then we are unnecessarily relying on a tool to fix an unintended change that was created by the developer in the first place.

This problem is not limited to diffs or logged changes. If you are using any decent version control system, this can easily turn your day into a conflict nightmare when someone commits a new change in a group of aligned statements while you also have local changes in some of them. In this case, even if you are not editing the exact same line, it will cause a conflict that could be easily prevented.

Code alignment adds unnecessary changes to the SCM and increases the likelihood of code conflict.

Remember that in Git conflicts don’t happen only in regular commits. They can happen when:

Reverting a series of commits or a Pull Request.
Rebasing or Merging a branch to be on par with the master branch.
Cherry-picking changes.
etc.

There is always the likelihood that the target branch has a different alignment than the source branch.

Atomic changes are totally lost.

"What if I change my alignment in a separate commit?" you might be asking. You can do it, but be aware that it shouldn't be in the same Pull Request. If you revert a Pull Request with alignment changes, you are still messing with concerns that are not intended for that Pull Request. You still have to fix the conflicts that happen. Why all this trouble?

Code alignment prevents your changes on the version control system to be atomic.

Those are simple examples, now imagine dealing with that inside a complex system handling a conflict resolution. You just helped the nightmare to become worse.

As if it is not enough, there is the human factor. Every decent developer understands that the code should be consistently organized to have value. And code alignment helps to provide a false sense of constant organization. If you don't care about aligning your code, you have consistency by default, but if you do, you need to document it and make sure that everyone will actually align the code. Otherwise, it will feel the effect of the Broken Window Theory and eventually become inconsistent.

Code alignment adds one more thing to worry about, which increases the likelihood of becoming eventually inconsistent.

All of this is not just restricted to node require statements, it applies to all similar code alignment cases. Take for example the properties of an Object Literal:

A code example of a standalone Object Literal with all properties aligned with spaces before the colon

It has the same problems stated above.

Code style discussions are a waste of time until you start wasting your time by not discussing them.

Don't lose your time aligning code. It's not the end of the world, but it's an important aspect if you want to use every alternative available to create something that is maintainable. If you don't, there are other good resources on the subject.