Does code style matter?
I’m currently building my third engineering organization. This means that on three separate occasions someone thought “this seems like a good idea” while handing me, an obvious joke of a man, a set of keys to their precious property.
Long ago, when my dad handed me the keys to our family’s VW Vanagon so that freshly-licensed-16-year-old-Ben could drive us home from church, I promptly ran into a curb with such force that our front tire exploded. After what is perhaps my second most humiliating tire change, my dad still had me drive the rest of the way home.
Is this a metaphor for leadership or just an anecdote?
Things That Matter
When building an engineering organization, especially if you are coming into an existing culture, I’ve found that one of the hardest problems is determining what matters and what doesn’t. A leader, (ir)regardless of domain, only has so much capital to invest in the culture of an organization. One can only lead so many things, so the things one leads need to be especially important. Not only does that sound smart — it might actually be true. And to actually scale an organization, the bits and pieces a leader has to offer need to be instilled rather than directly led. The Things That Matter needs to be boiled down, documented, handed-off, and co-led by other members of the team.
Is code style one of these “Things That Matter?” In no uncertain terms (and I expect many highlights on this well-constructed sentence): code style totes matters.
I believe that platform-specific style guides are requisite for a successful engineering organization. This is a Medium post, and although I’ve already broken some rules by meandering a bit and ruminating on non-sequitors, I will attempt to boil my thoughts down into bullet points rather than further non-sequitorial meander-ment.
(Pssst — have I told you about my most embarrassing tire change?)
Six Stylish Reasons
Style guides remove the need for an entire class of disagreements. When there is a document outlining twenty five specific and actionable Ways of Doing Things, developers don’t need to waste their time debating these twenty five things.
Style guides remove cognitive burden by removing trivial choices. When programmers are a-programmin’ (and a-programmin’ is what they do), they shouldn’t need to think about where class members go or recall the variable prefixes used in this specific mother-effing file. Once a style guide is digested, each contributor’s brain can offer just a little bit more toward other Things That Matter. Let’s call this the coding equivalent of the Steve Jobs outfit.
Style guides transform individual contributions into team contributions. Code should never be the personal property of a contributor. When we adhere to style guides, we give some of our code ownership to the team. Every line of code should look and feel like it belongs to the team, not to the contributor.
Style guides make it easier to do code reviews. As my first witness, let me direct your attention to point #1 about removing an entire class of disagreements. What’s more, style guides provide predictability and reduce friction. When a developer doesn’t know where to find a variable declaration, they have to spend time searching for it. When a programmer doesn’t know from the name of a member whether it’s private or public, they have to hunt down this information.
Style guides make it easier to learn new systems. Unsurprisingly, an unfamiliar piece of code feels more familiar when it adheres to a common style guide. Contributors understand new systems more quickly when those systems look like all the other code they spend their time wading through.
Style guides provide built-in instruction for more junior contributors. They naturally guide contributors toward best practices. This point has a hidden lesson inside. A bonus sub-bullet, if you will: this point is the only point that relies on a style guide actually being any good. Your style guide could be hot garbage — no I’ll go even crazier here: your style guide could be as bad as In-N-Out French fries and it wouldn’t invalidate the other five points.
Bonus Flamebait!
This may result in some angry comments (maybe even more than the In-N-Out thing), but platform specific style guides are important. C# is different than Python, sure. I take this as a given, though some (I believe misguided) attempts have been made to make One Style Guide to Rule Them All. I propose a stronger argument: writing C# in Unity looks different than writing C# for a .NET Core ASP.NET server. They are the same language but very different platforms. JS in a React application may need to look different than JS running on your node server.
Further Reading
Are you jonesin’ for a style guide? Maybe you’d just like an example to you can go off and over-engineer your own. Here are some good links: