Code Comments

Code comments are very important, but often overlooked. For practical reasons we need a lot of meta information about the code. For most code you need to know what output it produces, where it pulls the data from, and how it works. You also may need to know who wrote it and when it was written or updated.

If the query is simple, you should be able to read the code and figure out several of these questions. But it is a lot easier just to read notes left by the author. This is also true if you are the author. It is easy to forget.

One solution is code commenting. In SQL you can leave comments two ways.

Multiline Comments

The first type of comment encloses the text in a slash and a star (/*) and a star and a slash (*/). All text in between these characters will be ignored by the database. For example we can add a comment the code to create our person table.

/* This creates the person table. It holds one row per student. */
CREATE TABLE person (
	person_id CHAR(6),
	person_first VARCHAR(30),
	person_last VARCHAR(30)
);

Any text inside the comment will be ignored so we can do multiline comments. We can also put comments inside the code.

/*
	This creates the person table. It holds one row per student.
	The person_id is in the format "X00000".
*/
CREATE TABLE person (
	person_id CHAR(6),  /* Example: X00000 */
	/* The student's first and last name. */
	person_first VARCHAR(30),
	person_last VARCHAR(30)
);

Single Line Comments

The other way of commenting is to prefix a line with two dash characters (--). Any text after the two dashes to the end of the line will be ignored by the database. We can put code before the two dashes and it will be executed. We can also mix the two types of comments in the same query. So we can rewrite the code above as below.

/*
	This creates the person table. It holds one row per student.
	The person_id is in the format "X00000".
*/
-- Last update: 2025-10-10.
CREATE TABLE person (
	person_id CHAR(6),  -- Example: X00000
	-- The student's first and last name.
	person_first VARCHAR(30),
	person_last VARCHAR(30)
);

Commenting Out Code

Comments also allow us to selectively deactivate code. Suppose you have the SQL to create the person and awards tables in the same file. But then you decide to delete the person table and re-create it. If you run the file it will give an error that the award table already exists and cannot be created. We can comment out the code to create the award table without deleting the code.

/*
	This creates the person table. It holds one row per student.
	The person_id is in the format "X00000".
*/
-- Last update: 2025-10-10.
CREATE TABLE person (
	person_id CHAR(6),  -- Example: X00000
	-- The student's first and last name.
	person_first VARCHAR(30),
	person_last VARCHAR(30)
);

/*
-- This creates the awards table.
CREATE TABLE award (
	award_id CHAR(6),  -- Example: X00000.
	award_fund CHAR(6),
	award_offered FLOAT,
	award_accepted FLOAT,
	award_disbursed FLOAT
);
*/

As you develop your code, commenting out code can save you a lot of headache. It is not uncommon to delete code thinking it is not needed only to find out later you were wrong. This can be especially vexing if you are modifying someone else's code. It also allows you to temporarily disable sections of your code so you can tear it apart for debugging.

Next

Next up...quoting.