MySQL Procedures : Standard/Best Place For Code Documentation?

Question

I'd like to put a paragraph or so for documentation on each of my MySQL procedures: date, author, purpose, etc. Is there a standard, accepted, or best place to put this kind of documentation?

For example, In MSSQL, some IDE's will generate a template for you to start coding your procedure; it comes with a little place for code documentation.

USE [MyDatabase] GO
/****** Object:  StoredProcedure [dbo].[StoreRecord]    Script Date: 04/29/2010 09:21:57 ******/
SET ANSI_NULLS ON GO
SET QUOTED_IDENTIFIER ON GO
-- =============================================
-- Author:      
-- Create date: 
-- Description: 
-- =============================================
ALTER PROCEDURE [dbo].[StoreRecord]
-- ... more code ...

Answer 1

MySQL provides a short (64 character) comment associated with each stored procedure (function) that is displayed as part of SHOW CREATE PROCEDURE (or FUNCTION) results. Beyond that any comments in the code you write to defined stored procedures and functions are stripped when MySQL parses them. As an example:

mysql> DELIMITER //
mysql> CREATE FUNCTION SimpleExample( cid INT )
         RETURNS INT COMMENT 'Returns the argument plus 5'
         /* ===============
            None of this comment gets stored in the database.
            =============== */
       BEGIN
           RETURN cid + 5;
       END//
mysql> DELIMITER ;
mysql> SHOW CREATE FUNCTION SimpleExample;

+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Function      | sql_mode | Create Function                                                                                                                                                             |
+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| SimpleExample |          | CREATE DEFINER=`ovis`@`localhost` FUNCTION `SimpleExample`( cid INT ) RETURNS int(11)
    COMMENT 'Returns the argument plus 5'
   BEGIN
       RETURN cid + 5;
   END | 
+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

mysql> SELECT SimpleExample(8);
+------------------+
| SimpleExample(8) |
+------------------+
|               13 | 
+------------------+
1 row in set (0.00 sec)

I know of no other standard for including documentation as part of stored procedures and functions. There are plenty of people who document their code, of course, but each project has its own practices. If you like what you're used to, stick with it; there's nothing preventing the same comments from working in MySQL. If you want some way to locate the comments from a function in a live database, you might consider using the COMMENT characteristic to point to a file+revision in your source code containing the original definition of the function where additional comments exist.