Written by 13:00 Database development, MySQL, Statements

How to Comment MySQL Code: Best Practices

CodingSight - How to Make the Best Use of Comment Function in MySQL

Comments are used to add information to the code. It is mostly ignored by the compiler, but human specialists can read those comments when they view your code. Comments are essential for developers because they have limited time, and commenting allows them to get valuable information at once or note some crucial details in regards to the code. Accessing this data lets them make the right decisions and work faster.

MySQL Comments It’s Useful

Comments are helpful for you personally and for anyone who may need to read or edit this code later. But how exactly?

  • Comments can be placeholders when coding. At that moment you might assume something, and you’d know whether your assumption is true in the future.
  • Comments can document your thoughts or be notes for yourself so that you won’t forget your doings when coming back to them later.
  • You can include comments on what you have done in your code for other programmers to understand it better and quicker (coders’ time is very, very expensive).
  • You can use comments to temporarily disable or enable buggy parts.
  • Commenting on each line of a script makes it simpler to track where bugs might lie within the program.
  • Comments in MySQL code can explain what certain lines of code are doing, or why you chose some particular approach to avoid any misunderstandings (for example, when some parts of the code are intended for some section or the particular purpose that you should understand clearly),
  • You can write an entire paragraph explaining all the details about the code section if needed for newbies or people from other projects. Commenting is often needed when writing complex MySQL queries with many clauses such as INNER JOINs, GROUP BYs, etc.
  • MySQL commenting allows you to make notes about what you’re doing. This helps others understand how and why you did something so they can maintain or modify it as needed.

Does MySQL Support Comments?

Yes! MySQL comments are most often used in conjunction with languages like SQL and PHP where we can insert them into a text file or script using the comment function * / (e.g., /* This is my comment */). They’re typically just as easy to use anywhere else, too.

How to write a comment in MySQL

The comment function will let you write any text to add a comment in MySQL. It does not affect the final output as long as it comes before or after a definite pre-programmed character.

To add comments in MySQL, you can use the following symbols: /* */ or # or (double-dash).

/* */ will work for any situation where you want to start and end your comment at that point without using anything else (like single quotes).

# is used for one line of code at a time

also applies for one code line at a time. Don’t forget to put a space after this double dash.

In your code it would look as follows:

-- this is a comment
# this is also a comment

Here’s the difference between the one-line and multiline comments:

mysql> SELECT 1+1;     # This comment continues to the end of line
mysql> SELECT 1+1;     -- This comment continues to the end of line
mysql> SELECT 1 /* this is an in-line comment */ + 1;
mysql> SELECT 1+
this is a
multiple-line comment

Here’s another example of a multiple-line comment:

SELECT contact_id, last_name, first_name
 * Author: TechOnTheNet.com
 * Purpose: To show a comment that spans multiple lines in your SQL
 * statement in MySQL.
FROM contacts;

Commenting Using the # Symbol

The basic hash commenting style can be inserted into text like this:

Select * from users ; # this will list users

Commenting Using the Double-dash (–)

This is more or less the same (don’t forget the space). The standard SQL doesn’t actually require you to use the space there, but MySQL uses it to avoid problems with commands like SELECT 10–1.

Select * from users ; -- this will list users

Commenting Using the / * and * / Symbols

This multiline commenting, unlike the previous two examples, doesn’t have to stop at the end of the line.

Select * from users ; /* this will list users */

Executable MySQL Comments

As a rule, comments are ignored by whoever’s on the other end (because they’re for programmers only), but some comment types – executable comments – enable the code running on some systems.

In our case, executable comments allow you to use SQL codes that will be executed in MYSQL only, not in other databases.

Executable comments should be contained within asterisked slashes, as with the usual code:

/*! MySQL-specific code  */

However, these executable comments require a specific syntax like below:

/*!##### MySQL-specific code */

You need the !##### part to signal executable comments. It represents the minimum version of MYSQL that can execute commentaries.

Instead of the first hash, substitute the main version of MYSQL. Instead of the second, the younger version and the versions of the patch are substituted for the last 2.

Only MySQL 5.1.10 or later version can run the following comments:

KEY (k)
) /*!50110 KEY_BLOCK_SIZE=1024; */


Comments in MySQL make programs easier to read by adding more details. You can think about them as somewhat similar to hashes – they reduce the time required to understand the code or identify some parts of it drastically by providing snippets that capture the essence of the text. If you’ve ever worked with zero-knowledge proofs or tried to log into Facebook through Google, you’ll know what we mean.

That’s why it is essential to comment on your code and know how to do it correctly. Keeping your code accurate with informative notes makes the lives of all involved specialists easier.

Tags: , Last modified: March 29, 2023