CODEWITHSUNDEEP
sql-servermetadata
Andreas Grech
Andreas Grech

Reputation: 107950

Writing a proper Table Description

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?

Upvotes: 3

Views: 5981

Answers (5)

RBarryYoung
RBarryYoung

Reputation: 56725

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

Upvotes: 1

ftank99
ftank99

Reputation: 51

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.

Upvotes: 1

dkretz
dkretz

Reputation: 37645

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.

Upvotes: 0

Booji Boy
Booji Boy

Reputation: 4582

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?)

Upvotes: 0

kristof
kristof

Reputation: 53824

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?

Upvotes: 3

Related Questions