menu

Code with Style… Use Style Guides

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  RubyJavascriptSASS, and PHP.

What Do Style Guides Define?

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.

  • The character count in a line of code.
  • How to indent lines (tabs vs spaces & number of spaces)
  • Spacing around parenthesis, curly braces, operators, and similar
  • Documentation practices
  • Language use preferences, generally suggesting use of more performant constructs over less ideal options
  • Naming conventions
  • Exception handling

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.

Why Style Matters

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.

Future-Proofing

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.

Quality Assurance Through Code Review

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.

Linters and Other Code Formatting Assistance

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:

  • JSHint - http://jshint.com/
    This is JSHint, a tool that helps to detect errors and potential problems in your JavaScript code. It can be installed into most text editors or IDEs as well as ran online.
  • Rubocop - https://github.com/bbatsov/rubocop
    RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide. It also has options for customization. It can be ran via the command line and, generally, easily integrated as a command to be used from your text editor.
  • Hound - https://houndci.com
    Review your JavaScript, CoffeeScript, and Ruby code for style guide violations with this online service. It integrates directly with GitHub and automatically adds comments to style guide violations into Pull Requests.

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.

Conclusion

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.