This post originally appeared in my Chainline Newsletter.
I've been thinking about why we argue about code, and how we might transform vehement differences of opinion into active forces for good.
My thoughts spring from a very specific context. Ten or twelve times a year I go to an arbitrary business and spend three or more days teaching a course in object-oriented design. I'm an outsider, but for a few days these business let me in on their secrets.
Here's what I've noticed. In some places, folks are generally happy. Programmers get along. They feel as if they are all "in this together." At businesses like this I spend most of my time actually teaching object-oriented design.
Other places, folks are surprisingly miserable. There's a lot of discord, and the programmers have devolved into competing "camps." In these situations the course rapidly morphs away from OO Design and into wide-ranging group discussions about how to resolve deeply embedded conflicts.
Tolstoy famously said that "Happy families are all alike; every unhappy family is unhappy in its own way." This is known as the Anna Karenina Principle, and describes situations in which success depends on meeting all of a number of criteria. The only way to be happy is to succeed at every one of them. Unhappiness, unfortunately, can be achieved by any combination of failure. Thus, all happy businesses are similar, but unhappy ones appear unique in their misery.
Having now taught a fair number of classes, I've experienced various unhappy shops and am beginning to discern some common criteria for happiness. In this newsletter I'll discuss just one on them, with more to follow in future newsletters.
Today I'm interested in choices of syntax, i.e whether or not your shop has agreed upon and follows a style guide. If you're surprised that I'm starting with this apparently mundane issue, consider yourself lucky in your choice of workplace. If you're shaking your head in rueful agreement about the importance of this topic, I feel your pain.
Why Have A Style Guide?
I firmly believe that all of the code that I personally have to examine should come to me in a consistent format. Code is read many more times than it is written, which means that the ultimate cost of code is in its reading. It therefore follows that code should be optimized for readability, which in turn dictates that an application's code should all follow the same style. Adhering to a common style saves you money.
What Style Is Best?
Most programmers agree with the prior paragraph, but here's where things begin to break down. As far as I'm concerned, my personal formatting style is clearly the best. However, I'm quite sure that you feel the same. It's easy for a group of programmers to agree that all code should follow a common style, but surprisingly difficult to get them to agree on just what that common style should be.
The truth is, many stylistic choices are arbitrary, and purely a matter of personal preference. Choosing a style guide means building agreements in areas where we have strong differences of opinion about issues of little significance. It's not style that matters, but sameness of style.
Why Can't Teams Agree?
As I've already said, if you don't have a style guide, it's costing you money. However, if you can't agree on a style, the money may be least of your problems.
I have visited businesses where failure to come to agreement on this issue tore teams apart. The programmers had long since ceased verbal negotiations, choosing instead to employ change requests as an excuse to convert adjacent sections of code into their own preferred style. Code regularly flipped-flopped between competing styles. This not only made it difficult to discern actual changes in behavior, but it also infuriated the person who last touched the code the next time they looked at it.
These "style wars" are ostensibly about formatting code, but are actually about power. In mild forms, the wars create tension and cost money. In virulent forms, they poison team morale.
Don't I Deserve To Have My Own Way?
Well, no.
This is really a question of who gets to decide, and your approach to answering it lays bare the fissures in your shop. It's common to have three distinct lobbies, each with their own opinions about styling.
There's often a group of senior programmers who are convinced that they are right and that they deserve to have their own way. These folks attempt to rule by fiat, and when fiat fails, they feel empowered to ignore group agreements and employ their own stylistic preferences. After all, who's gonna fire them?
It's also common to see a group of programmers who came from another language writing Ruby in a style more suited to that other language. These programmers make choices that help them understand the code, disregarding the fact that their styling choices confound everyone else.
Finally, there are the newbies who don't yet have firm opinions about style. Because they are experimenting with all the styles, their code is characterized by inconsistency. Bless 'em, they mean well, but they're confusing everyone and need an intervention.
I've listed only three groups, but if your business has splintered in this way you're likely contending with many more variants of style. Once divisions form everyone goes their own way and you end up with as many styles as programmers. In shops like this, when I ask "Can you tell who wrote a piece of code by looking at it," everyone answers "Yes."
How Can Teams Reach Consensus?
The styling problem is actually twofold. First, everyone has to agree on a guide. Next, everyone has to follow it.
If you're in a shop with a history of conflict, it's best to outsource the guide. The community has throughly beaten the what-should-code-look-like horse; there's no reason for you to duplicate this effort. Just search for "Ruby (or language of choice) Style Guide" and choose one.
Using an external guide allows you take advantage of the wisdom of the crowd while side-stepping internal squabbles. Most guides please and disappoint in equal measure, and so require compromises from all. Choosing an external guide means it's not personal when someone doesn't get their way.
It's not enough to just select a guide--once you do so everyone must follow it. The easiest way to enforce this is to put automatic processes in place to alert folks to violations in their own code. For Ruby, have a look at RuboCop, configured however works best for you.
Avoid appointing a human "style cop", which just forces someone to be an increasingly ill-tempered nag. Instead, supply programmers with the information they need to remedy their own transgressions. By the time a pull request is submitted, mis-stylings should long since have been put right. Pull request conversations ought to be about what code does rather than how code looks.
As a personal aside, I've been experimenting with Elm. My desire to format code like intentional Elm instead of awkward Ruby led me to install an automatic Elm formatter in my editor. I initially hated the look of the auto-reformatted code, but over the last few weeks I've transitioned from active dislike to genuine fondness. Repeated exposure to standard Elm styling gradually taught me to prefer it, proving again that normal is what you're accustomed to, and that it's easier to act your way into a new way of thinking than vice versa.
What About Code That Already Exists?
Ignore it. You don't have to re-style all existing code, just do better from this day forward. Defer updating old code until you touch it for other reasons.
Following this strategy means that the code you most often work on will gradually take on a common style. It also means that some of your existing code might never get updated, but if you never look at it, who cares?
If you choose to re-style code that you otherwise have no need to touch, you're declaring that changing the look of this old code has more value to your business than delivering the next item on the backlog. The opportunity cost of making a purely aesthetic change includes losing the benefit of what you could have done instead. The rule-of-thumb is: Don't bother updating the styling of stable, existing code unless not doing so costs you money.
What If I Hate the New Style Guide?
If you disagree with the style guide upon which your team agrees, you have only two honorable options.
First, you can obey the guide despite your aversion. As with me in the Elm story above, this act is likely to change your thinking so that over time you come to prefer the new style. It's possible that if you follow the guide you'll begin to like it.
Alternatively, you can decide you will not obey the style guide. Making this decision demands that you leave your current job and find some other business whose guide matches your preferred style. Go there and follow that one.
Notice that both of these choices have you following a guide. This part is not optional.
The moral of this story? It's more important for all code to be formatted the same than it is for any one of us to get our own way. Commit to agreeing upon and following a style guide. And if you find that your team cannot come to an agreement, step away from this problem and start a discussion about power.
Best,
Sandi
News: 99 Bottles of OOP in JS, PHP, and Ruby!
The 2nd Edition of 99 Bottles of OOP has been released!
The 2nd Edition contains 3 new chapters and is about 50% longer than the 1st. Also, because 99 Bottles of OOP is about object-oriented design in general rather than any specific language, this time around we created separate books that are technically identical, but use different programming languages for the examples.
99 Bottles of OOP is currently available in Ruby, JavaScript, and PHP versions, and beer and milk beverages. It's delivered in epub, kepub, mobi and pdf formats. This results in six different books and (3x2x4) 24 possible downloads; all unique, yet still the same. One purchase gives you rights to download any or all.
