Authored by on Thursday, Feb 5, 2015
Style guides should be an important part of your coding process.
No, I'm not talking about what font or theme you use in your text editor/IDE. Style guides are a set of coding conventions to follow in the context of a language or framework. There are style guides already available for many languages and frameworks. We have found this to be an important part of our process here at Greane Tree Technology. Here are some examples of style guides for Ruby, Javascript, SASS, and PHP.
There isn't an essential list of criteria for what a style guide should define. It can change with the language or framework. Here are some common elements.
This is not, by far, a full list. They can be as detailed or as simple as necessary. That level of detail is simply a matter of preference and can be ironed out through collaboration with others you are working with.
Readability is the ultimate goal. By defining indentation patterns, documentation practices, and the other elements in a style guide you are ensuring consistency. Issues can be easier to spot through irregularities in the code. With this consistency, code throughout a project, regardless of the number of people working on it, should all look like it was written by the same person.
When choosing a style guide there may be multiple guides out there for the language or framework you are using. Ultimately, it's a matter of preference when it comes to choosing one. It's important to discuss this with your team and ensure that everybody is on-board with the decision.
An added bonus to using the style guide is also efficiency. Once you've become used to using the style guide, it becomes more natural to do things the preferred way. You can focus your thoughts on the business logic for the application rather than style decisions.
After deciding on the style guide, I would also suggest archiving it in the project and to add a link to it from the project README file. This will notify all developers on the project, as well as future developers, of the best practices to be used.
Now, you could just link to the style guide externally. However, you should consider this. Let's say that is updated in the future at some point to say spacing around all parenthesis' now need a space where they did not before. Your team has already agreed upon the style guide as it was before. Should you spend the time to update your entire project? Personally, I would say it's not worth the effort. Archiving the style guide in your project prevents any confusion if the style guide is updated in the future.
That's not to say that your team can't add or edit the style guide as you see fit. Feel free! Just make sure that the team is aware of those changes.
During the process of learning the style guide, it's possible you'll slip up and miss something. Code reviews via Pull Requests on GitHub or BitBucket are a great way to monitor these. If you don't already use Pull Requests, I would highly suggest you use them as part of your process. Refactoring is important to keep your code clean and having another set of eyes review your changes can help a lot to spot issues.
There are a handful of tools available to assist with ensuring style guide consistency. These can range from plugins integrated into your text editor or IDE to services integrated into your version control system (eg: Git). Here are a few:
Personally, I have found using linters to be effective and use them with my editor of choice, Sublime Text. Feel free to test out the variety of options out there and come up with your own workflow.
You can make your own decisions on what style guides to follow or come up with your own. Just know it's important to make a decision to use one. Whether it's for you to find some consistency in your own code, to work more effectively with a team, or provide value to your client by delivering code that can be easily adopted by new developers when necessary, style guides are crucial for writing clean code.