Code Standards

By Najaf Ali

Experienced developers have strong opinions about syntax. Some abhor the idea of significant whitespace. Others dislike the use of one keyword over another with the same meaning. Some prefer small, brief function names and others long descriptive ones. These preferences are personal. If they were based on some objective criteria they would converge on a common set of rules.

Code standards are an agreed set of rules about code syntax that a project or codebase adheres to. They define things like which keywords to use/avoid, how code should be indented, naming conventions and other details that the authors decided to include.

Developers spend far more time reading code than they do writing it. They read code for various reasons:

  • Reading to debug
  • Reading to plan new work
  • Reviewing for errors and oversight

In a given work session, we each have a limited amount of cognitive effort. We're more efficient if we can reduce any unnecessary cognitive load in each of these tasks. Enforcing project-wide coding standards helps by allowing us to focus on what the code does rather than the awkwardness of its syntax.

The following are examples of ways that strangely formatted code might trip up a developer trying to read and understand code:

  • Non-idiomatic constructs that the average developer might be unfamiliar with
  • Confusing indentation that misrepresents code structure
  • Names that don't follow established conventions and might be misleading

While developers on a given project may not agree with a given set of coding standards, by adhering to a fixed specification they can at least get used to them and get the benefits of a uniformly formatted codebase.

Enforcing code standards

Manually enforcing code standards by having other developers review and find errors takes a hell of a lot of effort. It's probably too much effort to be worth it. Thankfully modern programming environments usually have some tooling to enforce code standards. The Rust compiler will give you warnings for non-idiomatic code. Go provides you with gofmt which automatically formats all code for you, taking all the work of adhering to code standards away from the developer (you can do all formatting on a build server in a post-push hook for example).

At Happy Bear Software we use Ruby to get most of our work done. The standard tool for checking code format in Ruby is Rubocop. Rubocop is highly configurable. You can disable checks as you see fit and change their parameters (e.g. maximum line length) to your liking.

This makes Rubocop very easy to introduce onto legacy projects or into Rails codebases. We can disable all but a few checks and exclude large portions of the codebase from checking, iteratively moving towards a better-formatted codebase.

Modern web development teams use build servers to run automated tests on a version of a codebase to decide whether or not the version is fit to push to production. If all of the automated tests pass, it serves as a good indicator that the code is ready to deploy. Running a code standards checking tool (like Rubocop) as part of your build process will make sure that no code gets to production unless it meets the standard.

An automated tool like Rubocop helps to move quickly past syntax-related debates on a development team. If the entire team feels that a standard is too strict, they can simply configure the tool not check against that standard. For junior developers who perhaps aren't used to coding to a standard, it gives them an easily verifiable tool to check their code against. By automatically running the tool, reviewers can skip code-standard infringements and just focus on the meaning of the changes.

Making your code adhere to a standard is a small part of running a high-quality development project, but it provides enough of a benefit that we try to run all of client work through Rubocop or an alternative tool.