Avoiding Release Anxiety 2: On the importance of creating a code Style Guide
This is part 2 of the Avoiding Release Anxiety series. Check out part 1 here!
"I'm not sure how to implement this feature, Johnny is the one who created this screen."
"Better to leave that code as it is, the guy who did it left the company a few months ago."
"We should postpone this because Ana is the best person to handle this and she's on vacation."
When teams start to grow, it becomes to difficult to track what everyone is doing. If the team has different ideas on what a specific piece of code should look like, you can very quickly end up with a project where nobody wanders outside the things they coded themselves. I've heard things like this and witnessed the consequences of the lack of a consistent style guides many times in many projects.
Style guides can be seen as an anti-pattern when the subject is speed and there is often resistence from developers that haven't been part of large projects, and indeed having a traditional bureaucratic process in this modern tech world seems very odd, but a strict style guide is critical to have a project scale to the point where you can have hundreds of developers like Uber.
Humans have an easier time understanding things that are familiar to them, which is why most people immediately label code bases from other teams as bad. When someone says "What a terrible architecture!" or "I can't understand this, it's so badly written" it's not that the code is bad, but that you are so used to what you wrote that everything else will feel off. The code could be bad indeed, but the opinions would remain even if it wasn't as you naturally search for the things that are familiar to you.
Now, imagine an app with a team of 30+ developers. At this point the company is likely divided in squads, so there's no conceivable way you could review everyone's pull requests. Even if you could, it's 20 different opinions competing with yours, so you're bound to lose a few arguments. The more people the more opinions will differ, and without a style guide every squad's codebase will feel like a completely different project in your eyes in this scenario.
After hearing phrases like the ones in the beginning of the article, you'll find that moving people from/to different squads becomes problematic. Because there's a big difference in code patterns from squads, a learning curve needs to be taken into account as your brain needs to be re-trained every time you wander into someone else's code.
Finally, the worst outcome of this becomes visible: code review becomes inefficient. A PR that has changes in the code of multiple squads is too complex to understand due to the mix of many people's mental style guide. This leaves you unable to properly process the contents of the PR, making bugs and crashes slip into production. Hotfixes are pushed, but the PRs are just as bad to understand and the problem repeats over and over. Tons of "legacy" code is created -- an alias for "code that's too scary to change". Features that longer to develop, and refactors are nonexistent. Enter release anxiety!
Now, not only this story isn't made-up, I actually made it much less severe than it really was. The lack of style guides can greatly harm the progress of a company, and the notion that it hurts speed is nonsense. The few minutes someone gained by ignoring lesser issues in a pull request once spiraled into hours of bug fixing and shipping hotfixes. Strict style guides actually give you speed in the long term!
When an entire code base is written in a style that is familiar to you, all code feels like it was written by you. Rapiddo was the first app where we created our own style guide, and it was also the first app where I felt like making changes in someone else's code was just as straightforward as making changes in my own. The presence of a style guide meant that I knew exactly where to look just like I was the one who wrote it as we strived to code in the exact same way. In the two years that this app lived only one critical bug was found in production, and it was in the very beginning -- way before we had a style guide. This played a huge part in making the releases stress-free.
Bootstrapping a Style Guide
For tips on creating your team's own style guide, I recommend taking a look at other team's guides. Here are some links to get you started:
- Ray Wenderlich's Style Guide
- Linkedin's Style Guide
- Google's Style Guide
- MovilePay/Rapiddo's Style Guide (mine)
In general, here are the things I personally find important to cover:
- How to build something in the app's architecture, detailing the desired pattern as much as possible
- Details on how to write clean code (I personally recommend this book) - How to name properties/methods (This is important for CMD+F reasons! Things need to be easy to find for everyone.)
- When to use delegation/notifications/closures, and how to use them
- Desired usage of specific syntax sugars, like the way you can write methods where the last parameter is a closure
- The order/position of properties and methods in the file, to allow quick lookups
- Usage of special components/abstractions
- Usage of comments/documentation
- Be strict! In the long term, the project becomes easier to handle to everyone.
An important thing to mention is that style guides are incremental. Don't worry about covering everything at once, new topics will naturally come up during code review. Here's an example where a comment resulted in a new addition to the style guide:
With time, the topics that matter most to you and your team will be covered and you'll have a complete guide.
Conclusion
In the end, it's all about how far you see your project going. Style guides are strict, have a learning curve and are hard to get used to initially, but if neglected, the lack of one ends up being one of the main reasons why a repository fell apart. In the long term, being able to seamlessly access and understand someone else's code in a team of 200 engineers is a large scale project's biggest strength.
Follow me on my Twitter - @rockbruno_, and let me know of any suggestions and corrections you want to share.