Why we have code standards and style guides
Code standards and code style guides are like two sides of the same coin. They essentially tell programmers in a team, or across a larger organisation, how to best write their code. Code standards are the rules and conventions at a high level, whereas code style guides are specific to a particular coding language. We have style guides for – amongst other things – HTML, CSS, JavaScript, PHP and XML.
Why have code standards?
There are many reasons why an organisation might want to have code standards, and there are some reasons we’ll cover for why you might not have them (yet).
Cost is a big concern: somewhere between 40–80% of the cost of a piece of software is in its maintenance. And given that the vast majority of code is not maintained by its original author, this cost can snowball rapidly as it takes more time for each programmer to understand the logic and style of the author.
At St Andrews currently, most developers have their own way of doing things, which may be fine for small, stand-alone projects but within an enterprise-level project this can lead to issues such as:
- inconsistent code in terms of organisation, syntax, formatting, and naming conventions.
- code bloat in production systems, often including code that is either never used or is out-of-date (e.g. hacks for redundant versions of Internet Explorer).
- multiple implementations of functionality, with the consequential maintenance overload due to multiple chunks of code that solve the same problem in different ways, and an inconsistent look-and-feel due to multiple implementations of similar features e.g. tabs, sliders.
- bugs and typos.
- uncommented or poorly documented code.
- unreadable code.
- code from one site linked to from other sites, that if updated at source runs the risk of breaking features implemented elsewhere.
While it’s obvious that these inconsistencies and issues can result from multiple developers working across multiple projects, it can also be true for solo developers working on single projects. In other words, developers can be inconsistent even with themselves in the same project. We grow and change as developers, hopefully getting better with time, and without standards we can write code that is strikingly different just 6 months later.
If code standards and style guides are good, why are you getting them just now?
It’s costly in terms of time and effort to figure out what these guidelines should be and get them documented, even if you’re adopting ones that are available from the programming world at large. In addition to this we’ve got the task of getting a consensus among developers on which particular style to use. It’s a bit like asking art students who their favourite Renaissance painter is, you’ll get many passionate answers that are all probably great answers, but the trouble is that you’ve got to choose just one.
What if we don’t have standards?
The consequences of not having code standards are many:
- code that is difficult or impossible to maintain.
- code that is fragile and easy to break in unknown ways.
- fear of updating or improving code that leads to forked code and/or duplicating functionality using different resources.
- maintenance overload.
- slows down development.
What is our objective with having these code standards?
Our objectives for introducing code standards and style guides are to:
- develop an agreed standard for all code and ensure that code within scope adheres to these standards.
- use industry best practices.
- promote efficiency in maintaining code.
- continuously improve our code.
That way we don’t have any of the scary, bad stuff that happens when you don’t have standards.
We want code that programmers can all work on, code that people can be proud of. When the code all follows a standard, it looks great, works great and the developers can all get onto more productive work rather than being bogged down on complex maintenance tasks.
What’s our scope for these code style guides?
We have begun with guidelines for the following languages:
- HTML
- Cascading Style Sheets (CSS), including pre-processors such as Sass.
- JavaScript, including frameworks such as jQuery.
- PHP
- XML, including RSS and XSLT.
As well as:
- Commit messages (for version control software such as Git).
- Markdown (for writing documentation).
- Sublime Text packages (standard packages for developing the DPL).
This is naturally quite a lot of work to define exactly what we want and how we want it, but hopefully you now have and idea of why we think it’ll be worth it. You can read our code style guides as we continue to work on them on GitHub.