The COMMENT clause
All database components (and database themselves) should have a COMMENT
clause in their CREATE
/ALTER
statements, and a *_COMMENT
column in the information_schema. For example:
CREATE PROCEDURE do_nothing()
COMMENT 'We''re lazy. Let''s do nothing!'
BEGIN
DO NULL;
END;
SELECT ROUTINE_COMMENT FROM information_schema.ROUTINES;
In fact most database objects have those clauses in MySQL/MariaDB, but not all. Views are an exception.
Comments in code
MariaDB and MySQL have multiple syntaxes for comments. Including executable comments (commented code that is only executed on some MySQL/MariaDB versions).
One can use comments in stored procedures and triggers, and those codes are preserved:
CREATE PROCEDURE do_nothing()
BEGIN
-- We're lazy. Let's do nothing!
DO NULL;
END;
But, there are a couple problems:
- This doesn’t work for views.
- mysql client strips comments away, unless it’s started with
--comments
parameter. So, by default, procedures created with mysql have no comments.
So…
Views have no comment. No comments in metadata, no comments in code.
This prevents us to create self-documenting databases. Even if names are self-documenting, we may still need to add notes like “includes sold-out products”, or “very slow”.
Criticism makes us better
As a final note, let me say that this post is not an attack against MariaDB or MySQL. It is criticism, yes, because I like MariaDB (and MySQL). Criticism helps, keeps projects alive, encourages discussions.
To explain what I mean, I’ll show you a negative example. Recently I’ve attended a public talk from a LibreOffice Italia’s guy. It shown us a chart demonstrating that, according a generic “independent American study”, LibreOffice has no bug, while MS Office is full of bugs. The guy seems to think that software lint-like can automatically search for bugs. First I wondered how can LibreOffice survive with a community that is totally unable to produce criticism. Then I realized why it is the most buggy piece of software I’ve ever tried.
Hiding problems is the safest way to make those problems persist.
I’m happy that my favorite DBMS’s get the necessary amount of criticism.
Federico