{"id":2581,"date":"2010-07-01T09:36:32","date_gmt":"2010-07-01T07:36:32","guid":{"rendered":"http:\/\/code.openark.org\/blog\/?p=2581"},"modified":"2010-07-01T09:36:32","modified_gmt":"2010-07-01T07:36:32","slug":"sql-good-comments-conventions","status":"publish","type":"post","link":"https:\/\/code.openark.org\/blog\/mysql\/sql-good-comments-conventions","title":{"rendered":"SQL: good comments conventions"},"content":{"rendered":"

I happened upon a customer who left me in awe and admiration. The reason: excellent comments for their SQL code.<\/p>\n

I list four major places where SQL comments are helpful. I’ll use the sakila<\/a> database. It is originally scarcely commented; I’ll present it now enhanced with comments, to illustrate.<\/p>\n

Table definitions<\/h4>\n

The CREATE TABLE<\/strong> statement allows for a comment, intended to describe the nature of the table:<\/p>\n

\n
CREATE TABLE `film_text` (\r\n `film_id` smallint(6) NOT NULL,\r\n `title` varchar(255) NOT NULL,\r\n `description` text,\r\n PRIMARY KEY (`film_id`),\r\n FULLTEXT KEY `idx_title_description` (`title`,`description`)\r\n) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='Reflection of `film`, used for FULLTEXT search.'<\/strong>\r\n<\/pre>\n<\/blockquote>\n
It’s too bad the comment’s max length is 60 characters, though. However, it’s a very powerful field.<\/p>\n
Column definitions<\/h4>\n
One may comment particular columns:<\/p>\n
\n
CREATE TABLE `film` (\r\n `film_id` smallint(5) unsigned NOT NULL AUTO_INCREMENT,\r\n `title` varchar(255) NOT NULL,\r\n `description` text,\r\n `release_year` year(4) DEFAULT NULL,\r\n `language_id` tinyint(3) unsigned NOT NULL COMMENT 'Soundtrack spoken language'<\/strong>,\r\n `original_language_id` tinyint(3) unsigned DEFAULT NULL COMMENT 'Filmed spoken language'<\/strong>,\r\n `rental_duration` tinyint(3) unsigned NOT NULL DEFAULT '3',\r\n `rental_rate` decimal(4,2) NOT NULL DEFAULT '4.99',\r\n `length` smallint(5) unsigned DEFAULT NULL,\r\n `replacement_cost` decimal(5,2) NOT NULL DEFAULT '19.99',\r\n  ...\r\n) ENGINE=InnoDB AUTO_INCREMENT=1001 DEFAULT CHARSET=utf8\r\n<\/pre>\n<\/blockquote>\n
Stored routines definitions<\/h4>\n
Here’s an original sakila<\/strong> procedure, untouched. It is already commented:<\/p>\n
\n
CREATE DEFINER=`root`@`localhost` PROCEDURE `rewards_report`(\r\n IN min_monthly_purchases TINYINT UNSIGNED\r\n , IN min_dollar_amount_purchased DECIMAL(10,2) UNSIGNED\r\n , OUT count_rewardees INT\r\n)\r\n READS SQL DATA\r\n COMMENT 'Provides a customizable report on best customers'<\/strong>\r\nBEGIN\r\n\r\n DECLARE last_month_start DATE;\r\n DECLARE last_month_end DATE;\r\n ...\r\n<\/pre>\n<\/blockquote>\n
SQL queries<\/h4>\n
Last but not least, while not part of the schema, SQL queries define the use of the schema. That is, the schema exists for the sole reason of being able to query it.<\/p>\n
Where did that<\/em> query come from? Which piece of code issued it? Why? What’s its purpose?<\/p>\n
Looking at the PROCESSLIST<\/strong>, the slow log, etc., it is easier when the queries are commented:<\/p>\n
\n
SELECT\r\n \/* List film details along with participating actors *\/<\/strong>\r\n \/* Issued by analytics module *\/<\/strong>\r\n film.*,\r\n COUNT(*) AS count_actors,\r\n GROUP_CONCAT(CONCAT(actor.first_name, ' ', actor.last_name))\r\nFROM\r\n film\r\n JOIN film_actor USING(film_id)\r\n JOIN actor USING(actor_id)\r\nGROUP BY film.film_id;\r\n<\/pre>\n<\/blockquote>\n
Conclusion<\/h4>\n
Source code commenting is an important practice, and usually watched out for. SQL & table definitions commenting are often scarce or non-existent. I urge DBAs to adopt a comments coding convention for SQL, and apply it whenever they can.<\/p>\n","protected":false},"excerpt":{"rendered":"
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 […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"enabled":false},"version":2}},"categories":[53,5],"tags":[60,21,20],"class_list":["post-2581","post","type-post","status-publish","format-standard","hentry","category-development","category-mysql","tag-coding","tag-sql","tag-syntax"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p2bZZp-FD","_links":{"self":[{"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/posts\/2581","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/comments?post=2581"}],"version-history":[{"count":22,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/posts\/2581\/revisions"}],"predecessor-version":[{"id":2649,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/posts\/2581\/revisions\/2649"}],"wp:attachment":[{"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/media?parent=2581"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/categories?post=2581"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/code.openark.org\/blog\/wp-json\/wp\/v2\/tags?post=2581"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}