Coding Style Guides

If you know me you probably know that I sincerely believe that for a project to be successful you need to have both a style guide and automatic enforcement of that guide (linting).

I am always surprised when I speak with other developers, how few work on teams or at companies that have and enforce style guides.  This post will discuss the why so that we are all on the same page and ready to get started on creating and implementing a style guide on your team, company, and project.

So why do I need a style guide?

  1. Avoiding bike shedding.  As developers we generally have a lot of strong opinions.  When syntax formatting is not agreed upon we will inevitably devolve into cave people arguing over trailing commas or spaces versus tabs.  A style guide allows your team to argue once, make a decision, and move on to more important things.  Once a team agrees on a certain set of styles it is then taboo to discuss syntax outside of formally revisiting a style guide.
  2. Onboarding.  When new team members join, point them to your style guide as a first step before they jump into the code. Once a person understands the style and formatting it will be much easier for them to focus on the code rather than style.
  3. Readability.  When a code base has one style it is much easier to read.  When you have to context switch between coding styles it is a distraction and decreases efficiency.  When you read a book and every third paragraph has a different style or formatting you have a bad reading experience, code is no different.
  4. Team cohesiveness.  As a team when you write code in the same way you come to understand each other better.  You give your team something that you can all agree upon.  You may think of this as ridiculous but when you work on teams with diverse participants it creates a common ground where everyone is comfortable.  It gives you a starting point on which you can start bonds and friendships.  Nothing creates more animosity than seeing code formatting that doesn’t follow your view of what is correct.
  5. Code Quality.  Cohesive style makes you think about the code you are writing.  It makes you take a another look at the code before committing. With a consistent style it is easier to see errors when code looks slightly off.
  6. Code Reviews.  When you don’t have a style guide you spend time looking for style errors because they are the easiest to find.  Once you no longer have to look for formatting issues you can spend your valuable time actually reviewing the code and what it does.
  7. Prohibits Laziness.  I have worked with people who thought doing certain things because they had to get a feature out was an okay thing to do.  The response was always, “I’ll do that in another commit”.  One such instance was adding inline styles.  When I finished that contract 8 months later those CSS styles were still there.

So why do I need to enforce a style guide automatically via a build system or git hooks (linting)?

  1. If you don’t enforce a style guide no one will follow it. Once you create the style guide you will put it in your repo’s wiki and then no one will ever look at it again.  I have seen and heard this over and over.
  2. Code reviews will start being about styling and not substance.  If you add it to the linting system no one has to worry about style.  Lack of linting also creates real jerks out of normally nice people.  I hate being the bad guy who points out style issues in every commit.  It makes me look petty and mean but someone has to do it. TBH If you don’t follow the style guide that we as a team agreed upon I’m going to call you on it. Automatic enforcement means that a computer is calling you on it not me.  That makes me happy again.
  3. Commits will be squared away before they go into revision control.  Code will be at a minimum compliant before being pushed to github making it not possible for code with style  issues to be merged in.
  4. Style guide enforcement tools also lint for errors.  This in and of itself is reason enough to implement.

What is holding you back?

  1. Your team can’t agree on one style.  If your team can’t agree on style you have issues deeper than a style guide will fix.  If you come to an impasse setting down a team style guide it is time to make staffing changes.
  2. You don’t have time to create and enforce a style guide.  It should not take more than a couple hours to a day to decide on a style guide.  It should take no more than one developer  no more than one week to implement.  The tools are quite good these days. You will get this time back within a couple months in code reviews alone.
  3. My team lead, manager, product, business, etc doesn’t see the value.  Have them read this post.  If they don’t agree you should probably do yourself a favor and ask to join a new team or start looking for a new job.  Many times companies will find excuses not to implement a style guide.  You are not a unicorn, you are not special the same issues you face we all face.  Seriously, if they don’t see value here they won’t see value in anything but the quickest way to get features out.  Then they will be upset the code is buggy, difficult to maintain and, slow to change.
  4. I am the only developer on the project why do I need this?  Will you work on and maintain this project forever?  What if the project gets bigger and requires other developers?  What happens if you leave the project or company?
  5. This project will only live for a short period of time.  That’s awesome! The best time for a style guide is when starting.  If you do several projects like this add the style guides to your seed.  Adding linting should take an hour or two on a brand new project.  Just do it.  You never know when that project will take on another life.  You know that prototype you built that product let you throw away?  That has never happened.
  6. I have a huge codebase how do I add linting after the fact.  I have added linters to code bases with hundreds of thousands of lines of code.  All new code gets linted.  If you make changes to a file fix the lint issues first then make code changes.  Over time this will help you get the whole code base compliant.  Linters these days are also really good at automagically fixing your code.  Make some of the styles warnings which will show up in yellow but not block commits.

My next post will outline how to create a style guide.

Till then, JB