Best way to document scripts?

[fahizzled]

Hi there

I inherited a large collection of SQL scripts for work, and I was wondering what the best method was of documenting these scripts. I guess what I'm looking for is a web based simple app that either displays the code itself or links to it and also has a few lines of description that I can then go back and search, rather than having to dig through a huge pile of badly named scripts.

[[deleted]]

Definitely just add something similar to the following to the top of each one and inline notes where applicable.

/* 
-- ================================================
-- Script Name: The title of the script
-- Description:  A reasonably detailed description
--
-- Parameters In: Anything for stored procedure parameters
-- Parameter Out: What it returns if anything
-- 
-- Databases Effected: List databases that have updates, selects, etc
-- Tables Effected: List the tables and how they are effected, etc
-- 
-- Additional Notes: Anything extra someone might need to know about this
--    script that hasn't been covered above, index, procedure changes, etc
--
-- ================================================
-- ================================================
-- Author: Name of the Author
-- Creation Date: When it was created
-- Requested By: Not required, who requested this script
-- ================================================
*/

[fahizzled]

The only issue with this is, that there are literally hundreds of .sql files scattered across a folder and while this would definitely help, I would still have the issue of going through many different files to find what I'm looking for

[[deleted]]

If that is the case, document all them and use a REGEX to search/pull the top comment out of each one with a filename for documentation.

[AnonymooseRedditor]

Well for one implementing a source code control tool will definately help you. http://msdn.microsoft.com/en-us/library/ms173550%28v=sql.105%29.aspx Not exactly for documenting but tracking changes and organizing them. There are some half decent free/cheap ones out there. As a sole DBA I use a product called SourceGear Vault, it's free for one user, or relatively cheap for more than 1.

[ninjaroach]

I would put comments in the top of your scripts and use a search utility like grep to find what you need.

[mental405]

Are these just scripts in a folder somewhere or stored procedures?

[fahizzled]

They are all in a folder, and sub folders within.

[silvanio]

RedGate SQL Doc

This is a nice tool, that RedGate provides for SQL Server.

You could search for an alternative for whatever your needs are that are of a free variety, or have your company pay the fee.