Click here to monitor SSC
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Documenting Database Code: Structured Headers


Documenting Database Code: Structured Headers

Author
Message
Phil Factor
Phil Factor
Right there with Babe
Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)Right there with Babe (739 reputation)

Group: General Forum Members
Points: 739 Visits: 2937
Comments posted to this topic are about the item Documenting Database Code: Structured Headers


Best wishes,

Phil Factor
Simple Talk
Chris Chilvers
Chris Chilvers
SSC Veteran
SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)SSC Veteran (284 reputation)

Group: General Forum Members
Points: 284 Visits: 215
It's worth noting that pre-2008 the dependencies catalogue might not list all the dependencies.

Dependencies were tracked by object id, so if you create the objects out of order, or drop and recreate a dependency then the system looses track of that dependency.

http://msdn.microsoft.com/en-us/library/ms345449(SQL.90).aspx

This has since changed in sql server 2008
http://msdn.microsoft.com/en-us/library/ms345449.aspx

* edited - fixed urls
Steve Jones
Steve Jones
SSC-Dedicated
SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)

Group: Administrators
Points: 36008 Visits: 18728
I've always struggled with this. Red Gate's Dependency Tracker (grown out of a conversation that Andy and I had with Red Gate) really helps if you depend on these things.

I think one of the reasons I can be a control freak as a DBA is to ensure that I know, or can find out, what all objects are for.

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
blandry
blandry
Old Hand
Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)Old Hand (353 reputation)

Group: General Forum Members
Points: 353 Visits: 723
I think your idea is not only excellent, its vital - but your approach is a bit sterile and well, in my view, only partially useful.

Structured headers would be fine and probably a good idea, but that does not really translate over time to "useful commenting". I have been at this game for three decades and I have learned how important code commenting is.

The reason you comment your code is this: Someday, somewhere, you or someone else will be going back to your code and trying to figure out not just what you were doing, but what you were thinking when you did it. Useful comments can save a company many hours of re-analysis and since code of any kind is a company asset, it needs to be commented just as companies store records away for possible later retrieval with notes about the records.

Many people have said its silly to comment things like stored procedures - a good coder can read them and know whats going on. Baloney! Suppose a new hire is trying to get their feet wet, comments speed that process. Suppose an analyst is tracking down an error, or some cascaded effect, comments make that process fruitful. Since comments don't cost anything or inhibit the code itself - the more, the better.

In our organization, when we do code reviews, if a developer has not commented their code, its rejected and returned. I do not allow any uncommented code in our repository. As said, this is a company asset and I want to make sure that when that inevitable day comes, possibly long after I am gone, "old code" which may in fact be vital code, remains useful code because it is well commented for any new viewer of it to see, and understand.

Commenting and documenting your code is as important an ability as coding itself, because the code you are commenting/documenting is a company asset, and who wants an asset that no one knows what its for, how it works, or why it was created.

There's no such thing as dumb questions, only poorly thought-out answers...
Steve Jones
Steve Jones
SSC-Dedicated
SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)

Group: Administrators
Points: 36008 Visits: 18728
Blandry, I miss that. Too many places I've worked in the last decade didn't require code reviews. It seemed once Y2K passed without a big issue, lots of companies just didn't worry about documentation (again).

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
GSquared
GSquared
SSChampion
SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)SSChampion (14K reputation)

Group: General Forum Members
Points: 14369 Visits: 9729
I like the idea of an XML structure for commenting. Never thought of that myself, and haven't run into it as a practice.

Where documentation standards have been set for me, as opposed to me setting them myself, they've been similar, but not standardized. It's been a comment block at the beginning, with the name of the author, the creation date, and something short and sweet about what it's for.

Personally, I like comments in the body of the proc/function, that say what each section does, at the very least. Helps in debugging/enhancing later on. Not needed, of course, for something that's just a parameterized select or other single-statement CRUD procs.

But that's where it breaks down, isn't it? "Oh, this is so simple it can't possibly need to be commented and have full, formal documentation!" Sure, makes sense. But what's the break-point where it needs documentation? Or is it a gradient from, "needs a few comments" to "needs full-on documentation", depending on some complexity judgement of the code?

- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread

"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
Andy Lennon
Andy Lennon
Ten Centuries
Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)

Group: General Forum Members
Points: 1392 Visits: 826
i'm terrible with documentation. i put descriptions into procedures in a comment block up top and have additional brief descriptions for the business functionality of discrret sections within them. i don't think i've ever commented a table (never even occured to me) and have certainly never written up anything like a comprehensive document for overall database structure. I'd like to get in the habit, since on more than one occassion i've been asked to review code i or a co-worker wrote 2 years before to explain why it's suddenly "not working" (bollocks, of course).

Unfortunately, client-side pressures and my boss being even worse about documentation/commenting than i am conspire to prevent such sensible actions. : /
dld
dld
SSC Rookie
SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)SSC Rookie (30 reputation)

Group: General Forum Members
Points: 30 Visits: 415
We have gotten into the habit of formatted documentation in the header with standard stuff at the top describing who, what, when, etc. Then a revision section with numbered revisions, again with who, what, when... Then in the code we will reference additions or changes by the revision number with any additional comments required. You can get a sense of how the code evolved. This can, of course, get messy if there a lot of revisions.
Bill Nicolich
Bill Nicolich
SSC-Enthusiastic
SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)SSC-Enthusiastic (121 reputation)

Group: General Forum Members
Points: 121 Visits: 543
I think Phil has got a good area here to investigate and put effort into.

I add a comment header to all programmability objects like stored procedures and user defined functions. Although I keep a few good pieces of information there like who, when, a change log, basic purpose and so forth I have not devoted much thought to this area. Perhaps somebody has done some serious thinking and, through this topic, we all can walk away with something.

The header is probably best if brief. The key pieces of information to best go there are probably fairly straightforward. One piece worth some consideration is whether a change log should go in the header--you know, like the VSS change log that can be set to automatically append to the header as a comment.

Now Phil focuses on structured headers. The comments here have already drifted to code comments which is also an interesting and obviously related topic. Here I'd like to see the same XML comment subsystem used as is in use with C#: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx. Why reinvent the wheel? I imagine that parsers could be extended fairly easily to account for the additional double dash that would go in front of the tripple foward slash to extract the comments such as "--///."

I haven't seen much on this yet, but I suppose the topic of commenting T-SQL code that's rendered by mGrammar will come up--and through that, some standards will need to come out of it if they haven't already. Can anyone comment on this? Supposedly in the future, a growing percentage of T-SQL code will be produced through mGrammar and that whole Oslo-esque DSL (domain-specific language) family of solutions--and perhaps out of necessity these frameworks will drive the commenting solutions.

Bill Nicolich: www.SQLFave.com.
Daily tweet of what's new and interesting: AppendNow
Charles Kincaid
Charles Kincaid
Ten Centuries
Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)

Group: General Forum Members
Points: 1041 Visits: 2383
Great idea, Phil. By the way VB .Net has the XML comments too. They show up in the object browser. It forms the minimum set of documentation. But the barest minimum. We had talked about a "librarian" feature that would scanning all our source code and pull this data into some type of searchable repository. We have found that each of us has written the same routine, each in our own way, without knowing that anyone else had already done it.

Andy you are not alone. The thought that descriptive routine names and variable names are enough is pervasive and dangerous. All developers are lazy. (Especially me.) Working for a boss who is a developer is bad. You will share the same bad habits.

ATBCharles Kincaid
Go


Permissions

You can't post new topics.
You can't post topic replies.
You can't post new polls.
You can't post replies to polls.
You can't edit your own topics.
You can't delete your own topics.
You can't edit other topics.
You can't delete other topics.
You can't edit your own posts.
You can't edit other posts.
You can't delete your own posts.
You can't delete other posts.
You can't post events.
You can't edit your own events.
You can't edit other events.
You can't delete your own events.
You can't delete other events.
You can't send private messages.
You can't send emails.
You can read topics.
You can't vote in polls.
You can't upload attachments.
You can download attachments.
You can't post HTML code.
You can't edit HTML code.
You can't post IFCode.
You can't post JavaScript.
You can post emoticons.
You can't post or upload images.

Select a forum

































































































































































SQLServerCentral


Search