Regardless of the programming language you operate in, code can quickly become cluttered, unreadable, and difficult to understand. This issue is particularly compounded when you consider that every programmer has their own unique coding style and “best practices”, so the logic one developer uses (and thus, how they code things) might be different than your own, and vice versa.
One way to clear up the confusion and clarify what a line or block of code’s intent is, is to comment your code. We cover that very topic in this SQL programming tutorial.
When you mention writing SQL queries, commenting is not the first thing that typically comes to mind. Perhaps that is because SQL is such a simple language when compared to programming languages like Python, Java, or C#. Whatever the case may be, even SQL offers support for commenting code. In fact, commenting queries is considered a Best Practice for SQL.
If you are not familiar with the concept, commenting code is the practice of leaving “notes” explaining to other developers – or yourself when you review the code weeks, months, or even years later – what a particular line or block of code was intended for.
Single-line Comments in SQL
In SQL, a comment begins with two — characters. Once the SQL interpreter see those two — symbols, it knows to ignore any characters on that single line. Here is an example showing how to use a single-line comment in SQL:
- - This is a SELECT statement choosing data from the Books table SELECT AuthorName FROM Books;
In the above SQL example, the interpreter only sees the portion that reads:
SELECT AuthorName FROM Books;
The rest is essentially invisible.
Multi-line Comments in SQL
What if you want to place multiple comments that span multiple lines in your SQL queries? There are two methods to leave multi-line comments in SQL. The first involves just placing back-to-back single-line comments. For example:
– This SQL Query was brought to you by: – Ronnie Payne of SQL Emporium –********************************************** SELECT AuthorName FROM Books;
In the above example we demonstrate that comments are for leaving other information as well, outside of simply explaining code intent. Here, we use it to tell who wrote the code.
Another way database programmers can leave multi-line comments in SQL is by using the opening /* and closing */ characters. Anything that appears between the /* and */ symbols is ignored by the SQL interpreter. Here is an example:
/*This SQL Query was brought to you by: Ronnie Payne of SQL Emporium ********************************************* */ SELECT AuthorName FROM Books;
Best Practices for Commenting in SQL
There are several best practices for commenting in SQL (or any programming language really). First and foremost, remember that the idea behind commenting is to clarify what a block of code is supposed to do. If you comment every line of code, however, the code becomes cluttered and impossible to read. It is also an inefficient use of your time.
Instead, only use comments on code that is not readily apparent what it was intended for. For example, any SQL programmer should know that a SELECT statement is used to, well, select data from a table. Therefore, explaining what the SELECT does would be redundant and unnecessary.
Comments can also be used to debug code. If you are having trouble figuring out why a query does not work, you can comment out portions until you figure out where the logic flaw or syntax error resides.
Similarly, you can use this method when you are updating old code and want to leave the old code in just in case there is an issue with the new code or you need to reference the old code. Simple wrap the old block of code in comment tags and you will have preserved it without it being able to interfere with your existing codebase’s functionality.
Finally, you might want to consider switching from commenting on “what code does” to “why you want the code to do what it is” in some instances. Often your intention for code might be interpreted differently to other coders.