How we create and manage a ReasonML Code Style Guide at Avo in a democratic and open way
Alex Verein

Alex Verein

(Developer Advocate)

October 27, 2020

How we create and manage a ReasonML Code Style Guide at Avo in a democratic and open way

Today we open our code style to the public. Please share your ideas of new items to add to the guide in the issues section!

At Avo we write most of our code in ReasonML, a strongly-typed functional language operating on top of the Javascript ecosystem. It’s a great tool (I mean, strongly typed functional language on top of the Javascript ecosystem... need I say more?) and fun to work with. It also has its challenges.


There are particularly two challenges that are relevant to any development project, that become more apparent your programming language isn't mainstream:

a) Onboarding new people into the project
b) Maintaining code quality

Neither of those challenges are new. They are relevant to any programming language, but given the nature of ReasonML, building tools to address them becomes crucial for the effectiveness of the product development.


Luckily, there is an old and proven way to address those challenges - a code style guide. But, if a good code style for a popular language like Javascript or C++ is easy to find, when you work with a niche language like ReasonML you are left to create the code style on your own (or adopt ours 😉).


How Avo built a democratic approach to our code style

Here’s how we approach it at Avo. In our first attempt at defining a code style the project was already a few years old and we were 4 developers. 


We started out making a list of issues we face daily in the codebase. It was a collaborative document, everyone could submit there. Next, we discussed it at our developer roundtable. It's a meeting we hold every 3 weeks where all developers discuss matters related to engineering. 


One of the topics on that particular roundtable was our code style. We spent an hour going through the list of suggested ideas and ended the roundtable with an actionable - one of our engineers would make a subset of the discussed topics that everyone agrees on that would become the first iteration of our official Code Style Guide. The Avo ReasonML Style Guide was born. It felt great to have a code style. On the other hand it was small and definitely incomplete, that’s why we labeled it v0.1. We had to iterate and improve, so we designed a process for that.


We use Asana to manage topics to discuss in our developer roundtable, and we have an ongoing topic for code style contenders. There anyone can suggest a new rule for the code style. Then all the contenders are discussed at the meeting and the items we agree on go into the code style. We really like this approach because it democratizes our code style and brings all new issues to the attention of all developers, so everyone knows the latest state!


Today we open our code style to the public, you can find it in this GitHub repo. Please share your ideas of new items to add to the guide in the issues section!


Block Quote