Why we created our front-end coding standards and how we developed them

When learning to code, everyone develops their own personal style, has an opinion on standards, and the way code should be written. However, when you have to work as part of a team, there are times where you have to jump onto a project that you may not have worked on before and you may have to start editing or adding to someone else’s code.

More often than not, you might spend some time trying to decipher someone else’s code, or wondering why they may have made certain decisions, or written something in a particular way. You may find it difficult to read their code and start adding to it, overwriting rules or hacking your way around it. Then, before you know it, you can end up with a clunky mess that’s even harder to maintain and update.

We have definitely learnt this the hard way in the past.

At Razor, our front-end team have worked together for a long time, we all code to a good standard and take pride in our work. We share similar beliefs on standards and good practice, and for the most part, we came to the same conclusions about how we would like to structure our work.

Even in this scenario, we still encounter problems sometimes and we wanted to make a document that we can all follow, that’s natural and intuitive for the whole team and that is flexible enough to expand on it the future.

Here are some things to think about if you want to set your own coding standards.

Collaboration and communication are key

When writing our coding standards, we didn’t want to have one person dictate how others should code. The first thing we did was to decide the technologies and methodologies that we all like and use across most or all of our projects, which are:

  • Sass; we use Sass to write our CSS on all of our projects at Razor. Sass allows us to write styles that are more understandable and easier to maintain. It also allows us to separate our styles using partials, set up variables for flexibility, and mixins help make our styles reusable.
  • Bootstrap 4; we also regularly use the Bootstrap 4 framework to build our front-ends. It comes with Bootstrap’s source Sass files and enables us to create an attractive front-end quickly. Sometimes, Bootstrap can be too heavy for some projects and in this case we may choose not to use it at all or to only use parts of it.
  • BEM; We’re striving to use the BEM methodology to ensure that everyone who works on the project speaks the same language. BEM gives us a solid structure that is simple, easy to understand and one that we can all learn and use.

Next, we nailed out a few rough requirements:

  • Not overly complicated
  • Flexible
  • Human
  • Readable
  • Easy to familiarise ourselves with
  • Scalable
  • Maintainable

After we had gathered some requirements, the next step was to outline the problems we were having and figure out solutions for them.

Writing code is personal

We all organise our Sass files differently. We all format our code differently. And whilst we all stick to semantic markup and class names, we all tend to structure our code slightly differently.

These three main problems helped us flesh out some key principles which were:

  • Use partials well, don’t lumber everything in one big file.
  • Keep class names human and as simple as they can be. Use BEM when appropriate and describe the content, not the style.
  • Pay attention to syntax and formatting, we all need to work with each others code so this should be consistent across projects.

We also included a few more principles, not because we had major problems with these points but because they are always good rules to follow to ensure that our code remains neat:

  • Be mindful of nesting rules. Sass has many benefits but one of its draw backs is that it’s easy to nest too deeply. We want to stick to no more than three levels deep.
  • Take note not to use unnecessary markup, it makes it harder to read and work with. Stick to simple and semantic markup, and keep accessibility in mind.
  • We’re sure you’ll know most of this but it’s always good to familiarise yourself with basic CSS best practices such as using quotations around strings, preferable units and avoiding the use of !important.

Keep the audience in mind

We’ve tried our best not to dumb down our coding standards as we didn’t want to patronise the experienced professionals who’d be using them. The language used was very important as we didn’t want our coding standards to read like we were dictating or that we always know best. We don’t and things can change. We want our front-end developers to make their own decisions and we’d like our coding standards to become a talking point within our team. Our coding standards are really just guidance and for us to refer to and refresh our minds but they will definitely be edited and added to in the future.

And the results?

Our coding standards are on GitHub for anyone to see. We’re yet to see if they will make a difference as they’ve only very recently been written but we're confident that they will. Our standards aren’t set in stone and are likely to change over time, as they should, as we’re always getting better and learning new things.

And yes, the use of emojis is very important. ✌️