Coding standards aren’t for you.

Coding standards aren’t for you. featured image

They are for code quality, readability, easier maintenance, modular components, faster development and fewer errors. They are also for your team. And future you. Especially future you.

Before I talk about future you, let me explain what I’m calling coding standards.

What coding standards are not (and a bit about what they can be)

I am not referring to language-based coding conventions. Such as using camelCase in JavaScript variables. Or not putting semicolons at the end of expressions in Ruby. Coding standards also do not concern themselves with “right” or “wrong.” They concern themselves with “how.”

An example of what coding standards do mitigate is the age-old debate of tabs vs spaces. (We use spaces. Down with tabs.) Coding standards would also set the indentation amount of each nested line. A final example would be the spacing within a function definition:

function doesSomethingAwesome ( $someVar, $someOtherVar ) { … }

vs

function doesSomethingAwesome ($someVar, $someOtherVar) { … }.

Notice that lack of space within the parentheses? That is exactly the sort of thing a coding standard would define. Asking yourself why on earth would anyone concern themselves with something like that? We will get into that. Trust me, it is a debate worth having and can save some major headaches for developers.

A bit of background

Our default technology stack is PHP, HTML, CSS, JS and Ruby. Each of those have their own sets of coding standards used by various groups. Our coding standards are a bit of a hodge-podge between PHP PSR, PHP the right way, HTML/CSS style guide, Code Guide, Get BEM and Ruby style.

Our development team reviewed some existing standards. We then chatted about what we thought would work best for us. We continue to tweak them as we go and find better fits for our needs and individual coding styles. Their creation was a collaboration.

Coding teams should discuss what works for individual members when first establishing standards. There will likely be disagreements in various aspects. It is worth the time to make everyone comfortable with the coding style they will be writing every day.

Some of the tools we use to make sure our coding standards are adhered to can be found here:

Your IDE would run your code against your standards every time a file is saved. You would then get a list of issues you need to fix or be notified the code is clean and ready to commit. Some development teams also use continuous integration tools. They check against their coding standards before any code hits their repositories.

A bit about the benefits

I touched on some reasons to implement coding standards at the start of this post. The main benefit for coding standards is consistency. Consistency in file setup, naming conventions, coding style and formatting make working in a team easier.

Being able to scan a large section of code quickly and confidently will save many hours of maintenance in the long term. Knowing that your file setup has variable declarations at the top, followed by public functions and then private functions allows you to navigate to the target section faster. Once you’ve gotten to your desired area in the code, consistent formatting allows you to look over the control structures of your function and find the code that needs updated. Now your annoying maintenance work is that much closer to completion. Everyone loves that.

Maintaining legacy code can be a major pain. Especially if there have been many developers working on the project. Each has their individual coding style. Over time this can lead to some hard-to-comprehend code. Standards mitigate this by forcing the whole team to write consistent code. Eliminating the need to understand someone else’s thought process from days gone by.

Coding standards help with quality by helping catch poorly formatted code. For instance, it is better to compare strings with === instead of == or !== instead of !=. Need to find out why? A good coding standard would catch the instance of comparison with == and prompt an update to ===.

A bit about Future You

Past Me once was responsible for the front- and back-end of a project. Past Me came up with a very abbreviated class-naming convention that matched with the acronyms the client was using. It described each variable and class, and Past Me was saving several keystrokes. Past Me loved my naming convention. Future Me did not, unlucky for me, he did not exist yet and could not speak his mind.

Six months later I returned to the project to add some basic additions. My naming convention was now completely foreign. The acronym-based names were now hard to scan and understand. Past Me cursed my naming convention and swore to Future Me (along with a few other entities) to never have this issue again.

Don’t hate Past You like I did. Keep Future You in mind when deciding upon your naming convention – he or she is a major reason why it is in place to begin with. The trade-off between the mental berating that Future You will give Past You is not worth a few saved keystrokes.