#008: 3 Must-Haves for Any SQL Style Guide

No developer actually enjoys creating documentation.

We want to build things, not be part-time writers.

But we also all have our own opinions and egos when it comes to best practices.

We’ve all seen it happen at least once (or much more) in our career.

A few members on the team get into an extended debate about how something should be done, or be written.

I’m as guilty as anybody in this.

And, sure, major decisions warrant this type of discussion.

But constantly debating like this on minor decisions can become incredibly counterproductive.

One of the best pieces of documentation you can create to avoid this is a simple style guide.

This will help the team decide, and document, how things should be done.

It can then be referenced to answer minor formatting questions without needing to ask others.

So today I want to help you with this by sharing 3 of the most important things to include.

This will be focused primarily on SQL, but can be applied to any language.

Let’s dive in.

#1: Establish Naming Conventions

There could be an entire post just about naming conventions.

It seems so simple but yet is one of the most difficult things to decide on.

This is arguably the most important thing to clarify in a style guide.

It will help maintain consistency and avoid unproductive future debates.

Here are some example areas of naming conventions you should look to clarify:

Table Names & Aliases

• Should these be singular or plural (ex. customer vs customers)?
• Should table join aliases be fully spelled out or just a single letter?

snake_case vs camelCase

• When should words be broken up?
• If snake_case, what type of casing? All lowercase, only uppercase, only first letter, etc.
• Is this just for columns or should this be for table names as well?

Timestamp Columns

• Should they be written as an action word (ex. created_at) or as a noun (ex. create_date)?
• Always indicate timezone? If not, what is considered the default?

#2: Clarify Expected Case & Spacing

This will have a major impact on how consistent (and clean) your queries look.

A big downfall for most developers is that they get lazy with this part.

While it doesn’t impact the final result set, there is a noticeable difference between tidy and untidy queries.

Your goal as a team should be to put out the best product possible, and keep it consistent.

One thing to note here…

Correcting this during a review can seem nit-picky which feels passive aggressive.

A great solution is to implement a linter such as SQL Fluff to automate those corrections.

Here are some other common examples to clarify to help everyone follow a similar approach:

SQL Action Words

• All uppercase, lowercase or first letter?
• Examples of action words are SELECT, From, where, ON, and, Left Join, etc.

Indentations

• Should all columns in a SELECT statement be indented?
• Should the column list start on the same line as the SELECT or the following?
• Should there be new lines/indentations for each JOIN condition?

Overall Query Layout

• How/when to use CTEs or Temp tables?
• What is an example of the expected overall look for a query?

Some of these can be hard to understand strictly through text.

The best strategy is to include examples and/or screenshots wherever possible.

#3: Establish Preferred Approaches

There are many ways to achieve the same result with SQL.

And as developers, we like creative freedom.

But having agreed upon approaches upfront will make it much easier to read/review code.

Here are some examples:

Case vs Iff

• Both can give similar results, but which should be used?
• An example solution here could be:
  • If there are only 2 conditions, use iff, otherwise use Case

Booleans or Values

• TRUE/FALSE , 0/1 or Yes/No
• Be clear on when to use each, or which to default to

Trailing vs Leading Commas in the SELECT Statement

• This debate could probably also have an entire dedicated post.
• There are strong opinions, but just decide as a team and move on.

While creating a style guide isn’t the most exciting part of the job, it can be a huge asset for your team.

Removing guesswork around these concepts can make you much more efficient and avoid unnecessary debates.

Hopefully this will help inspire you to take action on creating your own style guide (if you haven’t already).

And if you need more help getting started, here is a great example Style Guide from the folks at dbt-labs.

Cheers,
Mike