Me Style, not Committee Style

(Note: This post describes my opinions on the matter, not Jobber's. At Jobber we have a healthy style guide and a dedicated group tasked with keeping it current and relevant.)

It started with K&R vs. Allman. Where do the braces go?

K&R

if(true) {
  do something
}

Allman

if (true)
{
  do something
}

(And many more variants existed then and now.)

Many a holy war was held over this.

Then we started defining more rules for how the code should look. Thus begat the code style guide.

It would talk about braces, and spacing and probably variable names and a number of other things.

Now we had a half-page of things to disagree about. And many a holy war was held.

Eventually, the stylesheet grew to a page or more.

Now we couldn't remember what we disagreed about. Thus begat the linter.

If we can't remember the rules, let's put them in a program and electro-shock developers when they misbehave. And now the computer itself was waging the holy war against developers.

Since we don't need to remember all the rules in our heads, we can create more rules. The electroshocks became a constant buzz. Lights dimmed.

This would not do. Think of the climate. Thus begat the prettier.

Now developers could type whatever the heck they wanted. Once they were done, the computer overwatch would "fix" the code to comply with the style bible.

And so the holy wars ended. Our computer overlords had won.

The above is only kinda tongue in cheek. I feel our current obsession with extreme style guides is misguided. I don't think we achieve a great deal by ensuring every developer's code on a project looks like every other developers.

The reason is almost always given as "faster readability". But really, if there is a blank line at the end of a file, will anyone care?

Sure there are outliers. We need some amount of consistency. But I contend that if we could somehow put a number to a coder's style, and then plot those numbers on a bell curve, anything within 1 standard deviation will be easily readable by everyone on the team.

Some current style "darlings" that may well be harmful.

Line Length
What should a maximum length be? 80, 100, 120, 1000?

I've heard people still stick to 80 because they believe that is close to the 60 that most books limit to. They point to studies showing that reading comprehension is best for lines around this length.

Well, I don't know about you, but when I'm looking at code. I'm scanning most of the code to find the place I need to pay attention to, and then I'm reading for deep comprehension. And guess what? Studies also show that long line lengths are better for scanning.

So do we optimize for the case of deep understanding that we do for a smaller subset of the code, or do we optimize for quicker scanning so we can get to the right place faster.

I don't know, but I sure do know that there is not a simple answer.

My preference. 100-120. We all have big monitors these days. Any shorter line length and we seriously detract from the vertical capacity of what we can see. And I know vertical space is precious to me. I put a lot of value in seeing more of the shape of the code vertically. Although there is a happy bound here also. I find having a monitor vertical gives me too much vertical context.

This suggests line length may well be a very subjective thing, and also that in a perfect world, we could easily change the line length for different tasks. We might be close to that. Prettier's aren't bad at shortening a line. Maybe we simply allow them to also lengthen lines when appropriate. Then we can move back and forth between optimals. (But I'd want the saved file to keep the choices the developer made rather than what the prettier has currently done.)

Braces
OK. For me, there is One True Brace Style. And that is K&R. But really, is it going to slow down a dev's reading comprehension if the brace is on the same line versus the next line. I don't buy it. I'm not even convinced it needs to be consistent in a given source file. But maybe I'm superstitious enough to not want to tilt at this windmill too hard. Keep it consistent.

Oh, and NEVER SKIP THE BRACES.

If most code does

if(true) {
  do thing 1
  do thing 2
}

and then if there is only a thing 1,

if(true)
  do thing 1

with no braces, you are just asking for a bug when someone comes along adding a thing 2 without noticing the braces were not there.

Whitespace
I think white space isa critical part of a developer's
ability to communicate
intent
      . Just
             like
                paragraphs
    are an important part of
organizing prose.

Sure, as always, things can be taken too far. (See my value of vertical whitespace). But don't enforce where vertical spacing is allowed/disallowed. Trust the craftsman.

Method Length
I hate it when I see a developer creating a method to extract some code just to bring the line length of a parent method down to some prescribed limit.

Again, there are outliers, and I'll certainly agree that shorter methods are easier to read. But it seems like current recommendations for method length are taking that argument to absurdum.

Sure, many methods can be reduced to 15 lines, but not all. Again, when I'm reading unfamiliar code, having to jump to another method just to confirm that what the method implies it will do by its name is really what it is doing is a disrupter not an enhancer. There are certainly times when code should be extracted to capture a specific intent that isn't really a part of the parent’s primary intent, but extracting code just to shorten a method isn't helpful and is sometimes the only way to get past an aggressive method limit.

We should be trusting the developer. If the code is more readable by extracting some, trust that they will. Or comment on it in a review. Don't make a hard, inflexible one-size-fits-all rule for this.

Trust the Craftsman
In the end, I suspect many of these rules have been brought in as we bring lots of new developers into the herd compared to the seniors. New developers have less of a sense of what makes code readable and maintainable. The way developers are trained doesn't usually include much reading of code any older than a few weeks ago. Or that others wrote. But solve this with mentoring, not lawyering.

I firmly believe that developers are craftspeople. In woodworking, fine furniture done by a craftsperson often has a distinctive signature. You'll know who likely did something (even a century later), or at least who they admired and modeled.

Furniture that looks exactly like every other piece is made in a factory. Nowhere near as valued.

I know this is pushing an analogy to an extreme, but do we really want our developers to be producing factory code? Is that a good thing? Sure, no one but another developer will see the "beauty" of their hand, but as we diminish the freedom of a developer to create what they consider beautiful code, I think we also diminish their ability to solve problems in a beautiful way. If they are forced to write factory code, will their mind be limited to factory solutions?

About Jobber
We're hiring for remote positions across Canada at all software engineering levels!
Our awesome Jobber technology teams span across Payments, Infrastructure, AI/ML, Business Workflows & Communications. We work on cutting edge & modern tech stacks using React, React Native, Ruby on Rails, & GraphQL.
If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!