CODEWITHSUNDEEP
mysqlcomment-conventions
DudeOnRock
DudeOnRock

Reputation: 3831

Conventions for commenting/documenting .sql files

How do you guys comment/document your .sql files? Are there conventions similar to those of javadoc and the likes? What is commonly done in large scale database-heavy applications like facebook, twitter, google....

Upvotes: 2

Views: 780

Answers (3)

emsr
emsr

Reputation: 16353

There are no commenting conventions for SQL like Javadoc that I've seen. This would be a great question to pose to the Doxygen people though.

On the other hand, several RDBMS allow this:

COMMENT ON TABLE table_name IS 'This is a comment';
COMMENT ON COLUMN table_name.column_name IS 'This is a great column';

This is more in keeping with the whole RDBMS philosophy - it's all about data. I don't know of any system that will generate nice documentation with this though. Also, I don't think this is standard yet.

I don't think MySQL does comments this way but Oracle and PostgreSQL do.

Upvotes: 1

Karl
Karl

Reputation: 3372

I don't know of any standard or tool. But I use a comment block at the head and sometimes explain complex clauses

Upvotes: 0

Michael Durrant
Michael Durrant

Reputation: 96484

My answer is that I've mostly stopped commenting as the comments get out of date and can then be misleading and worse than none.

I now try to make my objects (tables, columns, stored procedures, etc.) names as meaningful as possible.

Upvotes: 1

Related Questions