Architecture, Standards

T-SQL Documentation

This is a standard of how we should document databases and data structures.

Philosophy

In order to fully understand our data structures and to make our software more maintainable we want to have good documentation of our T-SQL. This helps lower errors in code and helps future developers understand why a database or data structure exists.

Documentation Guidance

  1. Database
    1. Each database needs to include a description and will be housed in an extend property that should be detailed enough to understand what the database is for and why it exists.
  2. Tables
    1. Each table needs to include a description and will be housed in an extend property that should be detailed enough to understand what the table is for and why it exists.
  3. Columns
    1. Each column needs to include a description and will be housed in an extend property that should be detailed enough to understand what the column is for and why it exists.
  4. Indexes
    1. Each column needs to include a description and will be housed in an extend property that should be detailed enough to understand what the index is for and why it exists.
  5. Foreign Keys
    1. Each foreign key needs to include a description and will be housed in an extend property that should be detailed enough to understand what the foreign key is for and why it exists.
  6. Views
    1. Each view needs to include a description and will be housed in an extend property that should be detailed enough to understand what the view is for and why it exists.
  7. View Columns
    1. Each view column needs to include a description and will be housed in an extend property that should be detailed enough to understand what the view column is for and why it exists.
  8. Stored Procedure
    1.  Each Stored Procedure needs to include a description and will be housed in an extend property that should be detailed enough to understand what the Stored Procedure is for and why it exists.
  9. Stored Procedure Parameters
    1. Each stored procedure parameter needs to include a description and will be housed in an extend property that should be detailed enough to understand what the stored procedure parameter is for and why it exists.
  10. Functions
    1. Each function needs to include a description and will be housed in an extend property that should be detailed enough to understand what the function is for and why it exists.
  11. Function Parameters
    1. Each function parameter needs to include a description and will be housed in an extend property that should be detailed enough to understand what the function parameter is for and why it exists.
  12. Type
    1. Each type needs to include a description and will be housed in an extend property that should be detailed enough to understand what the type is for and why it exists.

Recommended Tool:

Red Gate SQL Doc

http://documentation.red-gate.com/display/SDOC3/SQL+Doc+3+documentation?_ga=2.161850616.554049314.1493912665-2124116406.1492543729

spot the interweb manual flickr photo by zappowbang shared under a Creative Commons (BY) license

Tagged , , , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.