JournalApr 2015

A shipmate got to have a code

For a more recent look at our engineering process and code quality guidelines, take a look at our Software Engineering Playbook.

Improving our code quality has always been an important part of our process. To help us get closer to producing the best code we can, we’ve defined a set of rules we call Pillars. Here’s how it all came about…

With a few full-time frontend and backend developers on the team, most of us are highly skilled coders, and all of us are able to code to some extent. Still, all of us have different abilities, which means different approaches to writing the code. Plus there’s also a matter of personal preferences, which contributes greatly to the mess that is a co-managed codebase.

When we first started out, it was only 2 people working on the frontend code which made it quite easy to manage the codebase and collaborate on projects. But the team grew, more people learned to code and got involved in development, the projects were getting bigger and code—messier. Nowadays, there are often 3 people doing hands-on development work on a client project, and we try to rotate the squads so that no same person works on a long-running client project for more than 2 back-to-back sprints (1-2 weeks).

Front-end development principles

There was an obvious need for some kind of internal guide that would help us standardise the way we write our code, first of ourselves and later to help on-board new shipmates. Our internal projects became an even a stronger indicator of that. The original version of the current Hanno website, for instance, was built by 2 people but since then the team has grown and now we have 7 people touching that codebase as we iterate the design and build upon it.

So what did we do?

It didn’t just happen in a week. Improving our code quality has always been an important part of our process. Initially we’d take notes during projects and share our learnings on how to improve the quality of the code we were writing, among ourselves. Then, inspired by Thoughtbot, Isobar , Github and many others, we began defining a set of guidelines for ourselves—we called it Pillars.

Hanno’s code pillars on GitHub

Pillars in its current state only covers HTML and CSS (Sass), with JS and RoR guidelines coming up, and will always be a work in progress as a lot of it is subjective, and the more people you have on your team, the trickier it will be. How do you define the only way people will write code at your company? Who gets to decide what becomes a standard, a rule?

Having written enormous amounts of code, and used Sass exclusively for a few years, we each have developed certain preferences for how we like to write our code. But standardising it means giving some of these preferences up and accepting the new rules. It might be difficult to adjust and start following the new guidelines but it’ll benefit the team in the long run so every team member needs to understand the importance of it, and agree to compromise a little.

“… we should stick to standards here, so that we can get just a little closer to producing great code, all day long”

What we learned

Do it gradually, as a team.

We’ve been improving the quality of our code over time by helping new shipmates learn the ins and outs of frontend development during the actual real-world projects.

Run internal code reviews.

Base your standards on the internal conversations that you have while doing these. Understand why certain people like doing things in certain ways.

Document it.

As you start to create standards and conventions, find a way to get them written down. That’s what we’re trying to do with Pillars, in exactly the same way as we did with our Playbook. Writing things down saves time, and allows you to iterate.

Use frameworks.

Don’t start from scratch. We mentioned Thoughtbot and Isobar, and there are plenty of other teams who do the same. Many will make their code guidelines open source.

Return to open source.

If you learn from others, make your guidelines open-source too. The more people who use code standards, the easier life will be for everyone. We used a quick MIT license for Pillars.

What’s next, for us?

First off, it’s about time we refactored our own flagship stylesheet. The original was built during a mini hackathon we ran in Kuala Lumpur—it’s long overdue for some serious refactoring. Putting Pillars to use is going to make a huge difference, and regardless of standards we’ve grown a lot as designers & developers since then.

Ultimately, we want to make sure that every one of our projects has style guidelines enforced. So we’re planning to introduce proper linting to our workflows to enforce our internal rules as far as possible. We’re also going to look at hosted CI services which might help us even more.

Athenians Pillars photo by Jef Jones:

Frontend development principles photo by Jeremy Keith:

Posted by
Sergei Tatarinov

With the team since 2011, Sergei is a creative technologist who bridges design and engineering at Hanno.