I happened upon a customer who left me in awe and admiration. The reason: excellent comments for their SQL code.
I list four major places where SQL comments are helpful. I’ll use the sakila database. It is originally scarcely commented; I’ll present it now enhanced with comments, to illustrate.
Table definitions
The CREATE TABLE statement allows for a comment, intended to describe the nature of the table:
CREATE TABLE `film_text` ( `film_id` smallint(6) NOT NULL, `title` varchar(255) NOT NULL, `description` text, PRIMARY KEY (`film_id`), FULLTEXT KEY `idx_title_description` (`title`,`description`) ) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='Reflection of `film`, used for FULLTEXT search.'
It’s too bad the comment’s max length is 60 characters, though. However, it’s a very powerful field.
Column definitions
One may comment particular columns: Continue reading » “SQL: good comments conventions”