More SQL Please: Comments

Comments can be added to SQL and will not be evaluated as part of the statement. To add a single line comment, prefix the line with two dashes.

If you are using the MySQL engine, the hash symbol # is used for single line comments instead.

-- Find Canadian users for bilingual communications.
SELECT email_address
FROM users
WHERE active = 1
AND email_address LIKE '%.ca';

| email_address | |---------------------| | marcus@mcrawford.ca |

Comments can be added to the same line as code, as long as the comment starts after the code.

SELECT name_first, name_last
FROM users
WHERE active = 0
AND age < 30; -- Under 30 is our core demographic.

| name_first | name_last | |------------|-----------| | Simon | Chen |

You can make comments span multiple lines, otherwise known as block comments, by surrounding the comment with /* */.

Block comments allow you to add as many line breaks as you want and the comment will not end until it is terminated with the closing characters.

This example uses Functions which are explained in a later topic. The comment briefly explains the intent and the rationale behind the query.

/*  
    This query retrieves a list of unique
    domains that have registered on our site
    so we can see which companies have 
    adopted the product.
*/
SELECT DISTINCT 
    substr(email_address, 
        instr(email_address, '@') + 1
    )
AS domain
FROM users
WHERE active = 1;

| domain | |---------------------| | mcrawford.ca | | hellocorp.com | | aminiconsulting.com |

When you are working on queries, comments can be useful to quickly test new ideas without having to remove your existing code.

This example also shows a technique using a "dummy" WHERE clause that allows us to switch between subsequent lines without having to edit them.

SELECT name_first, name_last
FROM users
WHERE 1=1
AND active = 1
-- AND age < 30;
AND age > 35;

| name_first | name_last | |------------|-----------| | Elena | Moreno |

A few good rules of thumb for comments are:

Keep comments clear and concise.

Try to use comments to explain why something was done rather than what. Try to make your code as self-explanatory as possible.

An exception to the above rule is for large queries with complex logic. Sometimes an explanation helps with understanding.

Create a system for remembering to update comments when you update your code.

When you are writing your code and comments, imagine yourself or a colleague looking at it again months or even years later. You will thank yourself for writing good comments!