Documenting Stored Procedures
-
What standards do you guys follow for documenting stored procedures?
I am not talking about comments within the procedures, but more like a
schematic way of saying how each procedures fits in the application,
how they relate to each other , what invokes what, etc. I am often
trusted with reviewing dozens of procedures at a time for different applications
and comments within the procedures are not enough to get the big picture.
Right now I am asking developers to a visio with just boxes representing procedures
and arrows to show precedence/calls etc. Just curious how others are
doing it.
Thanks.
-
Honestly, I haven't found a good way to do this. I suspect some type of UML tool like rational would work well, but they are so expensive and you have to be sure that absolutely everyone uses it.
Steve Jones
http://qa.sqlservercentral.com/columnists/sjones
The Best of SQL Server Central.com 2002 - http://qa.sqlservercentral.com/bestof/
Follow me on Twitter: http://www.twitter.com/way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com -
We followed a method similiar to a C++ file header comments style where we will put all the information first, like the version information, creation information
but that contains the tables used in the SP, views, and other stored procedures etc..
Whether Rational has an SQL Design tool yet ?
Linto
-
For UML support for SQL please follow this link:
-
Not sure if this is what you're after but I have word template that we use to dcument all database objects. For sprocs this includes all parameters and column name/datatype for any record set produced. Also included for sprocs a section to describe basic functions plus callers, dependants and dependencies. I have it as word document but can't see how I can attach it. If anyone would like a copy - let me know and I can email it to you direct. Unless the site owners would like a copy for anyone to download.
. . Greg
Greg M Lucas
"Your mind is like a parachute, it has to be open to work" - Frank Zappa -
I tend to keep a Word document that lists
- Arguments and types.
- Variables and types.
- Return values
- Fields retrieved (if any).
- Dependencies.
Included in this will be a detailed description of the stored procedure.
The stored procedures act as an interface to the databases so my developers only need to know about the interface.
It is up to them to maintain application documentation that will detail which stored procedures they will use. Failure to document is a management issue resulting in the big stick with the nails in it being retrieved from behind the managers filing cabinet.
-
We use pretty much the same method as David and some others. It is really based in the "Programming by contract" concepts from OO design. The docs include the normal things like parameters and recordsets but we also tie in the application side to document what module is calling the SP. Just a little more detail for us.
Matter of fact, I call them Interface Contracts...
-
We use tools by CAST software (www.castsoftware.com). They allow us to visually identify the relationships between not only database objects, but application objects as well. We can also generate impact analysis reports. It's a fairly good tool, and we are not using all the options, but you might want to check it out.
-
I'm waiting for the built in source-control management in Yukon. While we regularly comment our SP code, it is a less reliable way of keeping track of purpose and changes than when we use source control tools, where we have "reminders" to comment our code on checking in.
rkgc
-
We address the issue by comments in the stored procedure. Then we wrote a web application to parse the comments and display them on our intranet. We included search engines written in sql for getting only the stored procedures with specific keywords.
-
We developed a method that searches each web page and it looks for a certain keyword in the page. Then it finds all the stored procedures for the web pages and lists what views it uses and then what tables are used in the views and it lists the tables that are directly used by a stored procedure. We also use a mtehod to populate the description of each field and run a stored procedure against it to build a data dictionary. So all of our documentation is automatically built. So at the end we know what web page calls another web page, which stored procedures the web page uses and how the stored procedures is designed and the table relationships without doing anything but adding a keyword into a web page. All done on the web (output to a word document) so when ever we want the latest design we click one button and there we have it. So our time as developers is never wasted doing documntation, it's all automatic.
Edward M. Sokolove
Edward M. Sokolove -
quote:
Not sure if this is what you're after but I have word template that we use to dcument all database objects. For sprocs this includes all parameters and column name/datatype for any record set produced. Also included for sprocs a section to describe basic functions plus callers, dependants and dependencies. I have it as word document but can't see how I can attach it. If anyone would like a copy - let me know and I can email it to you direct. Unless the site owners would like a copy for anyone to download.. . Greg
-
-
Hi Greg, could you please send me this template. My email.: danygregory@hotmail.com Thanks
-
Viewing 15 posts - 1 through 14 (of 14 total)
You must be logged in to reply to this topic. Login to reply