43. Comments

If you write SQL long enough, it is inevitable that:

You will forget why you made certain choices long ago
Other people will need to read, update, and use your code

Comments are notes you add into your code that explain what it does and why certain choices were made. Comments do not affect how the query executes, they are only there to help you (or others) better understand your logic. There are two types of comments in SQL.

Single-Line Comments

Single-line comments are set off by two dashes, --, and are used to write a comment on one single line. For example:

select
    *
from transactions
where transaction_date = '2023-11-28' --Giving Tuesday
    and amount >= 100

Here, I've included a comment identifying the hard-coded date in this query as Giving Tuesday, in case later someone sees the code and wonders, "What's the reason for this specific date being in here?" Once your database sees the --, it knows a comment is beginning and will ignore the rest of the characters on that same line when executing your query. You can use single-line comments pretty much anywhere:

--This query gets $100+ donors for the 2024 Gala Invite
select
    --We only need the account_id here, not names
    distinct account_id
from transactions
where amount >= 100
    --We only want $100+ donors from summer 2023
    and transaction_date between '2023-06-01' and '2023-08-31'

Multi-Line Comments

If you need to include a comment that's longer than these brief sentences above, you can use a multi-line comment. These comments begin with /* and end with */, and can span as many lines as you want; the database will ignore everything between your /* */. For example:

/*
This query finds all direct mail source codes that were 
created as part of Maria's gala events campaign.

Maria asked for the source_code only, no need to provide
any additional data. 

Originally executed on July 1, 2021
*/
select
    source_code
from source_codes
/* Gala events source codes are those that:

- Have first character M
- Contain 'EV'

*/
where source_code like 'M%EV%

Best Practices

Comments should generally be used to explain why you're doing something, not just what you're doing. This will help others (and probably your future self!) understand your intent, not just your syntax. I will often include a multi-line comment at the very top of my queries that lists:

The original date I wrote the query
A copy of the request (or summary of it) that I'm fulfilling with this query
A log of any changes I have made to the query over time

Such a comment may look like this:

/*
Request for $100+ Event Attendees, 2023-02-11

From Maria: "Hi Adam, I need a list of everyone in the database who 
has given a gift of at least $100 in the last three years and lives
in Ohio, Michigan, or Indiana. I plan to use this list to invite 
these donors to an upcoming Gala in Detroit."

Updated 2024-02-08: Ran this query again for the 2024 gala, added Illinois
*/

I will then include explanatory single-line comments in places where I have:

Hard-coded a value like a date or number in a where clause explaining why
Performed mathematical operations as part of a select statement
Included dense or very complex logic as part of a join or where clause

Developing documentation standards like this can save you a lot of time in the future as it makes troubleshooting, code re-use, and adaptation much easier.