Guide to the Style Guide

Let first start with what this post is not and that is a style guide for clothing, make up or hair. This is about Coding Style Guides, what they are, if you should have one and if so then what one. I will mainly be following it through with JavaScript, but the knowledge can be transferred to other languages as it is the principle that I am looking at.

What is a style guide?

A Style Guide is a set of rules for your code to follow. These rules start from as simple as putting a semicolon at the end of the lines, and only using single quotes around strings. However the rules can be expanded to describe how you should format your code, for example how to format a function, the file naming convention and how to set up error checking. In short it is a guide of rules and patterns for developers to follow to create a consistent and fluent code.

Style Guides and their practice have been about for many years, but I feel with more languages and standards being put in place they have become more prominent. One of the earliest writing is a book called The Elements of Programming Style, which talks about the coding rules from its time for Fortran and PL/I languages. Though the languages are more out of date, the principles are not and can still be taken into account for todays standards. Most tutorials and beginners guide to languages, will also have some kind of style guide in them, so you can learn from their patterns what to conform to.

These guides don’t have to just be words on a page as well. The guides are able to be built into your Continuous Integration Builds. This would mean when your application builds it can produce errors or warning about your code and how to fix them before you merge into the shared code base.  Better yet,  you can get extensions built into most all the common coding editors that will evaluate your code as you type or on save of the code. Therefore you don’t need to wait until the end point when you are checking in to find out your problems. This can save time and also drill in the practices to your mind, so soon you will be throwing out the styles as you go with no help.

Should you have one?

This is a simple question with a simple answer, yes. Why would you not have one of these in practice at your company or even in your personal workflow. To conform to a style guide is an easy task for anyone to get started as there are so many tools to test your code. However if you have a large code base and then you decide to get a guide in place then it could take sometime, but worth it. Think if you have all types of developers putting their own twist in the code base and then they need to read each other code. It would create a bit of a muddle as they would need to understand the previous developer patterns to understand the code. Worst thing would be, does that developer conform to the previous developer standard or put their own in. This would then create a hybrid that creates more hassle for the next developer.

As you can see the guides can benefit you a lot, but not just for other developers reading your code. When you are creating code you want to make sure it is readable by yourself as well. If you think about, that you might not come back to a peace of code for a long time, with a style guide in place and in practice, you would be able to read the code more easily. It also then gives you a standard of coding, so your not just spitting out some Frankenstein code that just about works, but instead you always have a consistent level of code produced. With consistence code and naming conventions it then also make life easier when your 30,000 lines down the bottom of the page and you need to remember how you call that method. The style guide that pushes you to have a pattern to your naming, will then give you the ability to know how the method will be named. Therefore you won’t need to hunt it down as you will either just know the name or at minimal know how to search for it.

The people it should also be benefitting is the other developers working on the same code and also the company that could be recruiting another developer. If the standard is in place then it doesn’t matter who walks up to your code, they will be able to read it easy and also be able to update the code easier. The other perks of following the guide are the same that will benefit the individual user like simpler to find files names, update code and keep consistency.

Which one?

Well 99% of the time I would say not to build your own, but there is that small 1% I would say yes. This 1% time I would say yes, is for if you are a big enough company to require your own style guide. As the guide is just for coding then there is not customer vision of this, therefore it is not vital that the style guide represents your company image. Saying that though, some companies may prefer to have there own rules to follow as it might fall inline with other style guide or other company procedures. Either way it should only really be done if they must have to.

The reason to still use a popular  open source one is because it is just that, open source. This would mean that when the ECMAScript gets updated or any other language versioned, the community will update the style guide to comply with the latest version. This can take some time if it is your own, to update to a new version and have meetings internally to decide what the update is. However if the open source owner or community do it, then you don’t have to.

This then also back up the point that if another developer is recruited, they may know the open source style guide and be able to pick up the code base easier. If the style guide managed by your company or yourself, then you have no chance of the developer understanding the guide first time.

If you do decide to be in the 99% section, then which guide do you go for? This is where the power of the internet comes in. As I mentioned at the beginning, I am focusing this on JavaScript, but it can be transferred to other languages. Therefore for the JavaScript world I would suggest Airbnb Style Guide, because from what I have read and researched it is the most used guide. Of course this doesn’t make it the right guide, but other than the majority of the developer community can’t be wrong, the guide also looks good. From me using it I can tell it is up to date, well maintained and well supported by other extensions like linters. This for me says it is a good choice to go for and so I would use the same method for looking at other style guides for other languages.

To find other guide I would suggest using a search engine to find a guide for your chosen language, or speaking of search engine, Google has a style guide for a lot of languages and it will of course be up to date. You can find it here on Git Hub.

Some Further Reading…


Advertisements

2 thoughts on “Guide to the Style Guide

  1. Pingback: Meetup - MK.js -

Leave a message please

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s