Skip to main content

Command Palette

Search for a command to run...

Consistency is key

A prelude to code conventions

Published
3 min read
Consistency is key
P

PHP & JavaScript developer, working in Drupal.

Sorry about this post being a bit messy in structure. I've used it as a place to dump my general thoughts before delving into more specific subjects.

Code conventions, naming conventions, style guides, and coding standards are essentially synonymous. They form an agreement with a set of rules that developers must follow when writing code.

Terminology

My take on the different parts of a code convention is as following:

  • Code convention
    Is the umbrella that holds the other sub areas.

  • Naming convention
    How you name your functions, variables, classes, files and other identifiers. Including which multi-word identifier used (snake_case, camelCase, kebab-case, etc).

  • Style guide
    Is about formatting, like max length of lines, indentation and end of line characters.
    A linter should be able to catch all formatting rules, and maybe even automatically fix them.

  • Coding standards
    This is broader and not (always) as dogmatic as other parts of the contract.
    An example could be to always (or never) use a singleton class instead of global variables.

This is all just rule of thumb, nothing’s set in stone ... and entirely my own opinion.
Most of the time these terms are used interchangeably.

Examples

Conventions come in all sizes, the depth of the the document is usually proportional with the size of the team that needs to follow them.
There's a lot of public code conventions, so even if you're just a small team, you have the choice of selecting a well written in depth convention to follow. A few examples could be:

  • The Google styleguides: A list of style guides used by google developers. These tend to be very thorough and in depth, they not only cover the visual representation of the code, but also best practices.

  • Airbnb JavaScript Style Guide: Is a JavaScript style guide, that is being used directly by many, but it's also a popular template for teams to build their own standards on.

  • PHP-FIG PER Coding Style 2.0: The closest you'll get to an official PHP style guide. It's a guide voted in by members of various PHP communities.

  • Javascript.info - Coding style: A quick walk through of what a style guide is, and some examples. This starts off with an excellent image that boils down an entire style guide to 1 visual representation.

The #1 rule

Follow the rules, and if there's no rules be consistent.

Sometimes it's hard to follow a style guide, not because its difficult, but because you know better, and following the guidelines produces code that'll hurt your eyes (and soul).
If this is the case get together with the rest of the team, and figure out if you should change your code convention. While waiting for the rules to change, stick with the older "wrong" opinion of how things should look.
It's easy to change your style guide documentation, but when you do you invalidate all previous instances of that rule. So have a plan to fix all that old code.

Code conventions

Part 1 of 1

My personal thoughts on different coding conventions.