April 25, 2018

Add some style to your code

If there’s one thing developers are renowned for, it’s arguing over the style of their code. The drama inspired by topics such as “tabs or spaces” or “should brackets go on their own line?” is second only to that timless classic of a question - “vim or emacs?”.

Beyond the message board arguments and the workplace debates, there exists a very real issue though: write in a poor style and it becomes difficult to read and understand, whilst writing in an inconsistent style simply looks lazy and rushed.

Obviously this begs a question: *how do you find the right style?* The answer is quite clear: let someone else do it for you, of course!

Using off the shelf styles.

Most languages appear to have some common style “conventions” - either officially sanctioned (i.e Python’s PEP-8), community driven (i.e PHP’s PSR-2), or even as a result of an guide shared by an individual company (i.e AirBnB’s Javascript Style.

Opting for one of these has some great advantages, namely (a) reducing the effort required to onboard a new developer, and (b) there’s often automated tooling available that can check source code adheres to the style.

Ensuring Code Conformity in the Build Process

Once you’ve picked the style that you - or your team - thinks is the best, it’s time to ensure that all new code conforms to the style. Although we could rely upon a simple trust system, whereby every contributer is trusted to adhere to the style, this rarely works; rarely from malice, but often by forgetfulness.

Nope, to ensure that all of our new code adheres to our style, we need a little help from our build process.

Git Hooks

https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks are awesome; and allow you to tie certain actions in to your workflow, such as running external applications on changesets prior to a commit.

Sounds like the ideal solution to run an automated style checker prior to commit, right? Unfortunately the type of hook that this task would be suited to - pre-commit - relies upon the configuration of the developer’s workstation. Obviously this isn’t ideal in teams spanning multiple many team members, or open source projects that allow contributions from volunteers.

Utilising Continuous Integration

Whilst Git Hooks perform their function at an individual developer’s workstation, by utilising the continuous integration process - i.e via Jenkins - you can ensure checks are run at the git remote level, actively preventing poorly formatted code from being merged in to the codebase.

This is done via a combination of remote branch protection - i.e not allowing users to push directly to master - and utilising a workflow whereby merge requests are required to pass automated testing before approval.

A few last thoughts

Utilising common code styles is a really good step to increase productivity on a team, as it not only reduces the time spent during review processes, but it also enables faster code comprehension.

Whilst the initial adoption of a new code style can feel a bit “different”, there are fortunately style checkers (i.e “linters”) for most languages, combined with IDE support for many. Similarly, there’s even a few tools that will attempt to fix your code for you! (i.e php-cs-fixer)

One of the most important parts of adopting a new code style is understanding that there will always be exceptions; and it’s ok to modify the guidelines slightly so as to fit your team better! This is about increased productivity - not developer punishment - after all!

© Fergus In London 2019

Powered by Hugo & Kiss. Source available on Github.