Hi! I'm Johannes Dachsel, a web designer and developer based near Heidelberg, Germany. This is my personal website. Get in touch

Johannes Dachsel

Coding conventions for small teams

Among constantly growing development teams, things like version control or issue tracking have become indispensable. Unlike those tools, coding conventions are often overlooked – some notes on my workshop last week.

I’ve been working alongside a client’s web development team for quite some time now, but it hasn’t always been that way. When I first started working with the company, there were just two of us: a PHP developer—mostly doing Magento e-commerce systems— and me, a front end developer/designer making websites.

The team has grown over the past few years. Today it consists of eleven developers working side by side on projects rather than just working on their own like we did when there were only the two of us.

Challenges of growing teams

As the company grew and people joined the team, we adopted tools like git and JIRA to tackle certain issues such as shared source code, version control and issue tracking. But eventually we were facing another problem: there were no coding standards that defined how we should write certain source code files.

At least none that the whole team agreed upon. Sure, everyone knew how to write HTML documents or style sheets but when it came to things like naming classes, indentation, semantics or using SASS, there were a lot of different opinions on what could be considered readable code.

Frankenstein code

Working without coding conventions can be very time consuming, especially when there are multiple developers involved in a project. Reading and understanding someone else’s code can be a real challenge, especially on large projects.

When developers keep editing the same files without any coding guide lines they often end up with some kind of Frankenstein code that everyone throws their own class names, indentations and document structure at. The result is almost every time very hard to maintain and it takes developers joining the project a very long time to work their way through the potpourri of different coding styles.

How we defined our coding conventions

The first thing we did was to find common ground - rules that we already worked by and that we all silently agreed upon. Then we looked at best practices suggested by w3schools, CSS guidelines and jQuery to develop our own set of rules for writing front end code. These included things like formatting, indentation, using and naming classes, variables and functions and so on.

Last week I ran a workshop on front end coding conventions for that particular development team. I also prepared a cheat sheet for everyone’s desk. You can download it here, perhaps it might be useful to you.

Prism cheat sheet
Prism cheat sheet for your desk

I think coding standards are invaluable in a collaborative environment. They ensure proper document structures, consistency and easier maintenance of legacy code.