Why Code Conventions Matter for a Development Team

Traditionally I've been a huge proponent of Knockout.js because it was a small library that wasn't interested in dominating a larger space. I used this in conjunction with Durandal.js and I really loved the developer experience. Over the last several months I've joined the Aurelia core team and I wanted to share some of the problems that I've recognized lately that have persisted in my previous code and highlight how Aurelia helps to solve them. I'll highlight how it does so through the use of conventions and why they are important for teams when choosing a JavaScript framework (or any language's framework for that matter)

Mythical 10x engineers are not 10x Teachers

I love the concept of 10x engineers. I've had internal conflicts and discussions with the teams I am a part of about how real the concept is. Are there really these super-hero coders out there who can fix all problems on their own? Probably. I've been on many projects in the past where I thought man, if I could just be the only one working on this I could finish so much faster!

The problem is that these 10x engineers usually refuse to teach anyone else or share what they are doing, they just knock out features.

It's also worth noting that in the situations where I wanted to run solo that as soon as a team had to come behind me and start maintaining the code-base they inevitably started complaining about patterns I used or tools / libraries and started refactoring. In some cases the teams spent more time refactoring than I did creating and usually they ended up with the same result, just in a fashion or pattern that they felt more comfortable with.

This is a huge problem in software development teams. Make no mistake, no other industry would allow teams of highly paid individuals to come in simply to refactor or redo what others have done. It adds no value.

Yeah yeah, we know the problem what's the solution?

What's a team to do?

A team is not a new concept that only exists in the software development. Teams exist in every industry, every social group, and everywhere we look. These concepts aren't isolated to our holier than thou industry of app developers. We can certainly continue on the path of thinking that our solution to the problem alone is the best to fixing the problem but the truth is that it's been proven time and time again the key is finding standardized ways of approaching problems and processes.

The problem with this is we all feel that our unique snowflake way of thinking is so cutting edge and perfect we usually don't consider that what we are doing works for us but may not work for others. So how do we get around this?

Adopting conventions

Conventions are nothing more than standardized work. Standardizing work is the key to improving, as shown in industries across the world. Ruby on Rails is a perfect example - I can write a bunch of highly-opinionated code that, if written according to standards, most RoR developers can pick up and build features on top of. Aurelia doesn't reinvent the wheel in this regard. We love to look at how we can learn from other frameworks or languages and adopt best practices. But this isn't an Aurelia, post, this is a convention post.

It's no different from building a car. If everyone puts the car door on in the same manner we can cross-train and improve on the process. If everyone has their own way of putting on the car door there is a good chance tracking down why quality issues occur is impossible because we can't figure out how the door got that way in the first place.

This is why standards are so important. With ES6/ES2015/ES(whatever-you-want-to-call-it) we've adopted some awesome standards in our code that helps the code be sharable across teams / team members. It's easy to spot a code-smell such as a function or method defined in the wrong spot. We define methods on our class. If we have an object that implements it's own methods it quickly becomes apparent that we need to extract the object into it's own class and implement the methods conventionally.

No one wants to create their own conventions and standards though unless you work for a Google or a Microsoft who has the resources to put together some geniuses on a committee whose only job is to look at these pie in the sky problems.

Fixing the Problem

Any team who shares a code-base (whether in the same office or remotely) should look to conventions in coding standards to improve their output. Everyone want to find the best talent in the world who fixes all their problems and a lot fewer realize that the difference between the best talent in the world and the talent we already have is good training and enablement.

Some starting points

Most coding style standards can be implemented using tools like jsHint or esLint. This let's your team decided on a set of standards and stick with them.

Here's some insight in general / code conventions I can give based on my experience -

Establish standards...

  1. for creating classes that include a maximum number of lines of code to make code more readable.
  2. that limit the number of characters per line to make code more readable.
  3. that enforce methods (functions) to only be created on the class-level, never on this or an alias.
  4. that react to changes to a property or state by calling a method, never put that logic in the change event handler.
  5. for deciding when / how to modularize your code, never refactor working code without consulting the team.
  6. for committing to official code-bases - never allow pushing directly to develop/master without a code review
  7. for planning work - never allow refactoring working code simply for style reasons
  8. for when to pair - any story that may take more than a day to complete (including tests) should require two developers to pair up on. (this prevents writing a bunch of code that works but doesn't follow the style)

What did I miss?

Let me know in the comments!