SQL Server: Writing a proper Table Description

Question

I am, for the first time, writing descriptions for my SQL Server tables (from the Description field in the Properties Window), and I started thinking about what to exactly write in such a field.

For examples, some tables are self-explanatory according to their titles...like a table called Albums in a "Music System". What description would you actually write in such a case?

And what 'other' information do you normally include in the description? Do you mention the relationships to the table?

Is there a standard, formal way for writing descriptions for Tables?

Answer 1

I believe a good object naming and design plus eventually a tool that would visualise you database structure (e.g. SQL Doc) is much better that adding a detailed description to each object.

The more you want to cover in the description the more likely it will run out of sync from the real database structure. E.g. if you want to document the relationship, then each time you change it you need to remember to update descriptions as well (on all the objects involved?) It is basically redundant information because it is already recorded in the schema. We do not want redundancy it the database do we?

Answer 2

I'd put the name of the jobs/programs/reports that use said table in the Description. This is unlikly to need constant updating and answers the question why does this table exist? (ie Who's data is this?)

Answer 3

I would also include the table's cardinality/relationship to other important tables. This may seem obvious, but often it is not so. For instance for tblAddresses you might have the description:

"This table is a parent table for address detail lines (tblAddressLines) and is referenced by (and NOT a child of) the Employees table (tblEmployees)."

Answer 4

If you are using source-code control, I can't think of any comment to put here that wouldn't be better used as an SCC comment. I think it's superfluous, and wouldn't use it unless your organization has a standard for it.

Answer 5

3 simple statments should do for a table description: one describing what the table holds, one describing the initial state of data in the table (empty or pre-filled), and one describing how data moves in/out of the table.