The Code Style Rules Worth Arguing About

title: The Code Style Rules Worth Arguing About published: true tags: java, programming, codereview, discuss

My first code review argument was about a brace. Same line or next line. A senior developer had opened my pull request, scrolled to a method I was proud of, and left a single comment: "brace style." Two hours of back-and-forth later, the code was unchanged, both of us were annoyed, and I had learned nothing about the system I was supposed to be shipping.

I have since sat in that argument from the other side of the table, usually with better manners, occasionally without. Somewhere along the way I started sorting the rules we fight about into three buckets, because the buckets predict how the fight ends. Rules with real effects win their arguments. Rules with no evidence end in either a coin flip or a formatter. And the fights that never end are the ones no formatter can settle.

The rules that actually pay

A few layout rules have consequences you can point at.

One statement per line, and one declaration per line, earns its place. When two assignments share a line, diff tools show one hunk for two changes, and review comments stop mapping to locations. The same family of discipline shows up in real bug postmortems: the classic 2014 Apple goto fail bug shipped because two guarded lines sat under an if statement that had no braces at all. Formatting did not cause it, but brace discipline would have made it visible.

Line length has a practical floor and ceiling that have nothing to do with taste. Lines longer than about 120 characters overflow side-by-side diff views and code review panes, which silently truncates the review itself. Google's Java style guide caps lines at 100 characters, and whether or not you like the number, the reason is concrete: reviews happen in constrained windows, and code that does not fit does not get read.

Wrapping long lines in the right place matters for the same reason indentation does. A continuation line that starts with an operator, or that visually blends with the next statement, produces the same class of misreading that bad indentation produces. When you break a line, break it so the reader can see the break belongs to the statement above.

That is a short list, and it is supposed to be. Most of the rules with observable payoff reduce to one idea: make the structure of the code visible to the reader and to the diff.

The rules that are pure taste

Brace placement on its own line versus same line: no study has ever shown a comprehension difference. Spaces versus tabs: the readability research that exists is thin, mixed, and mostly about prose. Import ordering, blank line counts between methods, whether to align assignments: these change how code looks and not what readers extract from it.

The honest move with this bucket is not to defend a position. It is to notice that the argument costs more than either outcome. Every minute spent on brace placement is a minute not spent on the boundary condition three methods down. Review latency is real latency. When a PR sits overnight because two people are negotiating blank lines, the deployment waits on decoration.

The fights worth having

Then there is the third bucket, the one no formatter will ever settle, and it is where review energy actually belongs. Is this method doing two things? Is this name a lie about the behavior? Is this null check hiding a contract violation that will resurface in production with a worse stack trace? Should this logic live closer to the data it protects?

Nothing in this bucket is about layout, which is exactly why it survives automation. A formatter can make two files agree on braces in milliseconds, and once it does, the brace argument is over, permanently, for every file that follows. No tool can decide whether OrderManager should own refund logic. That decision needs a human who understands the domain, and it is the only kind of style decision that compounds over the life of a codebase.

Set the taste bucket on autopilot

The practical conclusion I reached, and would offer to my younger brace-arguing self: automate the taste bucket, argue about the third bucket, and document the first one.

Automating taste is the easiest win in the whole business. A shared formatter configuration ends the brace debate at the speed of a build step, and the code stops carrying the history of every argument that produced it. For anything from a snippet to a whole file, on a machine with no IDE profile to import, there is JavaFmt, a free online Java formatter that runs entirely in the browser. For the first bucket, the rules with observable effects, the Java code conventions guide walks through which standards buy what, from line limits to statement-per-line discipline.

Argue about names and boundaries. Let the formatter have the braces. My senior colleague and I wasted two hours learning that the hard way, and the brace in question is still on the same line it started on.