You’ve heard a colleague say “You’re all smart coders. You can figure out how my code works!” as an excuse to let less-than-clear code slip in. This is bunk.
Well, let’s back up a bit. This is technically true. When you’re reading code, you probably should be able to figure out how it works. Complicated and unclear code is a fact of development. You’re going to have to know what that code does, and knowing how complicated parts of your language work is part of that.
But, on the other hand, you don’t have to write it. We should strive to be robust in both how we operate our programs and how our programs operate. A good style guide is a tool that helps you and your team approach this ideal. The Scout Motto works well here: Leave the code better than you found it.
Style guides help out for a number of reasons:
- Without lots of formatting changes, code diffs are more meaningful. Some code changed? Then it changed for a reason.
- People can’t get into silly formatting wars in the code itself.
- New programmers come up to speed more quickly.
- Experienced programmers can read code they’re not familiar with more quickly (including you 3 months from now).
- The rules aid “Convention Over Configuration”, which means more assumptions can be made.
- Some kinds of errors can be avoided completely with proper style rules.
But, you know this. The problem is that your colleague doesn’t. Most often, the idea that “We’re smart enough to figure this out” comes up when trying to introduce a style guide to developers who, until that moment, had all been coding in their own style. They’ll usually complain about something relatively innocuous. For example, a common cause of concern is the ternary operator. While there are people who don’t know what the ternary operator is, it’s very easy to explain: “It’s like an inline if statement”. Boom. Easy, right?
Here’s the thing, though: your colleague isn’t complaining about ternaries. They’re almost certainly complaining about being made to code a certain way.
One important and useful effect of implementing a style guide is that it removes a coder’s own personal styles and therefore their ownership and egos. People subconsciously “mark” code by coding in their own style. When you code with the style guide, that’s not as possible. And since you can’t tell who coded it just by the style, you don’t feel as though you’re treading on someone else’s toes when you change that code. This is good for making sure everyone feels they can make changes that are necessary.
Telling a colleague they need to check their ego isn’t going to help you implement a style guide, though.
You should remind them that they’re not coding in a vacuum. Writing code is about communicating ideas to other people. It just happens to be in a way that computers can run. If you don’t believe it, try writing some machine code. It’s not exactly what you’d would call “expressive”, even if it can be fun sometimes.
Since we’re not coding alone, we need to make sure people can understand us. Researchers of human cognition have recognized that people can only hold a certain amount of information in their head at once. You’d be forgiven for thinking this means that packing logic into a method is a good thing, because it sounds like the kind of conclusion you could draw. But packing information into a method is not the best way to handle things. While the logic is all visible in one place, unclear code almost always means you need to keep all that logic in your head in order to know what’s going on.
Said more specifically: a ternary, to continue the example, can almost always be
pulled out into its own method – a method which (according to Sandi Metz’s
rules) will be at most 5 lines, conveniently fitting one if/else
conditional. You then don’t need to know what kind of logic the original method
needs to do, you just need to know the concept of what’s being asked.
Setting aside the limits of cognition, we can also take a cue from our design friends and stop trying to cram the most information into a small space. Let the code breathe, like a good wine. We’re obviously not golfers here. Give that ternary a name. Let us see and appreciate its conditions. You’ll be able to absorb more information faster when you can recognize the parts individually. Like eating a fine meal, you’ll like it more if you don’t try to swallow it all at once.
Another objection to style guides is that if you’re nitpicking over all the smaller style violations, you won’t have time to actually understand what the pull request is trying to accomplish. In that case, you can always let the machines do it for you and automate part of your code review with Hound.
Lastly, this might be one of those times when you need to get your manager involved. If your colleague is really obstinate, they might put up roadblocks to every attempt you make at enforcing a style guide. But while your colleague might not be receptive to any of these arguments, your boss might be.
One of the most important things you can do to maintain the health of your project is to keep and stick to a style guide. Making sure other developers can easily read, parse, and change your code is essential to growing a maintainable project.
