1

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....

DudeOnRock
  • 3,685
  • 3
  • 27
  • 58

3 Answers3

1

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.

Michael Durrant
  • 93,410
  • 97
  • 333
  • 497
1

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.

emsr
  • 15,539
  • 6
  • 49
  • 62
  • I admit I didn't know I could add comments to the actual tables and columns. Thanks for that info! That would make commenting the actual .sql file redundant, if that is where I create those comments. – DudeOnRock Dec 16 '12 at 21:45
  • @DudeOnRock I found on Google how you add comments in MySQL: when you define columns with DDL at the end of the column definition add COMMENT 'This is a great column!'. – emsr Dec 16 '12 at 23:55
0

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

Karl
  • 3,312
  • 21
  • 27