A Scala Style Guide
I was a StackMob engineer and I moved to PayPal as part of their acquisition in December 2013.
Since I joined, I’ve been able to write a lot of Scala, and open source some of it with the support of a great team and open source advisors. A while ago, I released Cascade and Horizon. More on those in a later post.
Today I want to talk about a style guide for Scala that I just released.
Before I start, PayPal makes me put this part in - I’m not representing them here, just myself.
Let’s start with some history.
The “StackMob Days” #
The style guide started before I worked at PayPal.
My team and I at StackMob brought Scala with us to PayPal. Some people at eBay were already using Scala but the language was pretty new to PayPal and I think we had most of the experience.
And here’s why: before the acquisition, we had seen some crazy shit with Scala.
We started with Scala 2.8 and basically ported Java code to Scala syntax. Then we learned more about the language and did a second pass on the ported code. We did basic things like using for comprehensions, Scala collections, etc…
But by 2.9 we were writing crazy, full-fledged functional code. We used scalaz almost everywhere and sometimes it made my brain hurt. We could crash the compiler, exhaust the PermGen space, or crash a JVM each in a line of code. Scala & Scalaz give you a lot of power, and in production it turned into a headache a few times.
I learned a ton about functional programming and I even co-wrote an HTTP library using some not-that-crazy functional concepts.
By the time we got to 2.10 and 2.11 we had settled down and were writing more readable and uniform code. We had good ideas on how Scala code should look but we argued about them all the time.
Our style slowly evolved into tribal knowledge and we were pretty good about sticking to it. In code reviews, we stuck to that style about 70% of the time.
The “PayPal Days” #
When we got to PayPal, we had no code and a clean slate. We were starting a brand new project with a lot of experience with what not to do, and a little experience with what to do.
The first thing we did was ban Scalaz from our codebase. I realize that’s a controversial decision for some people but I’m not making a comment about the quality of the library, community or similar. Scalaz made the learning and readability curve way too high for us.
We wrote “plain” Scala code, but we still found a million and one different ways to write it. The debates continued, but we gradually extracted good practices and cut out bad practices (the latter was easy because we had a long list of things not to do).
The Style Guide Is Born #
The debates brought up nightmares about the days-long ongoing debates of StackMob, but this time we had them mostly written down in pull requests, not in our collective brains.
As Zach Holman says in his post about chat, having a record ensures nobody misses out on decisions. I took those records of our style debates and started making them more precise.
I created an internal repo and made preliminary decisions about what should go in and what shouldn’t. Everything was written clearly and precisely. I wanted to make sure that once a style guide was in, we didn’t argue about it anymore. That point is very important - debates slow our team down.
I even kept the name simple to avoid debates: “scala-style-guide”. Besides, naming is hard and I’m scarred by previous naming debates.
Growing it Internally #
Over time as I kept adding to the guide, I got people onboard it by enforcing it in code review. It seemed heavy handed to me at first and I don’t really like telling people what to do. But each decision was made by all of us and I could always point to the underlying discussion that spawned it.
The guide spread pretty quickly because everyone wanted to participate in the discussions. Now I had the opposite problem - I wanted to make sure the style guide stayed precise and debate-free so I added administrative pieces:
- Goals. I wrote goals into the guide. We have to follow them every time we change it and they ensure that it stays focused and useful.
- Contribution. It’s in Github and follows a pretty simple contribution strategy. Everyone on the team can contribute.
- Persistence. If it’s in the style guide, we all have to follow it and we don’t debate it anymore. And we have time to do our real work now.
Those pieces are still there, and we still get those benefits.
Open Source #
Now, the guide is big and comprehensive enough that I hope others will benefit from it.
My team and I obviously mostly agree with what’s in it, so I want input from the community.
Go read it (it’s short), comment on it, or submit pull requests on it.
I’m looking forward to hearing what you think.