Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 
        
Home       Members    Calendar    Who's On


Add to briefcase 1234»»»

Documenting Database Code: Structured Headers Expand / Collapse
Author
Message
Posted Monday, June 29, 2009 11:09 PM


Mr or Mrs. 500

Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500

Group: General Forum Members
Last Login: 2 days ago @ 7:03 AM
Points: 579, Visits: 2,519
Comments posted to this topic are about the item Documenting Database Code: Structured Headers


Best wishes,

Phil Factor
Simple Talk
Post #744168
Posted Tuesday, June 30, 2009 2:41 AM
SSC Veteran

SSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC Veteran

Group: General Forum Members
Last Login: Wednesday, April 9, 2014 9:26 AM
Points: 281, Visits: 181
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
Post #744233
Posted Tuesday, June 30, 2009 5:50 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Today @ 3:06 PM
Points: 33,169, Visits: 15,304
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
Post #744324
Posted Tuesday, June 30, 2009 6:36 AM


Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Monday, May 7, 2012 9:23 AM
Points: 304, Visits: 716
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...
Post #744359
Posted Tuesday, June 30, 2009 7:05 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Today @ 3:06 PM
Points: 33,169, Visits: 15,304
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
Post #744373
Posted Tuesday, June 30, 2009 7:21 AM


SSCoach

SSCoachSSCoachSSCoachSSCoachSSCoachSSCoachSSCoachSSCoachSSCoachSSCoachSSCoach

Group: General Forum Members
Last Login: Friday, June 27, 2014 12:43 PM
Points: 15,444, Visits: 9,596
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
Post #744388
Posted Tuesday, June 30, 2009 7:30 AM


Ten Centuries

Ten CenturiesTen CenturiesTen CenturiesTen CenturiesTen CenturiesTen CenturiesTen CenturiesTen Centuries

Group: General Forum Members
Last Login: Monday, May 12, 2014 1:27 PM
Points: 1,386, Visits: 824
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. : /
Post #744398
Posted Tuesday, June 30, 2009 8:25 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: 2 days ago @ 10:47 AM
Points: 23, Visits: 313
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.
Post #744451
Posted Tuesday, June 30, 2009 8:31 AM


SSC-Enthusiastic

SSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-Enthusiastic

Group: General Forum Members
Last Login: Thursday, December 12, 2013 1:09 PM
Points: 111, Visits: 541
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
Post #744456
Posted Tuesday, June 30, 2009 8:36 AM


SSC Eights!

SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!

Group: General Forum Members
Last Login: Thursday, February 6, 2014 12:59 PM
Points: 801, Visits: 1,962
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.


ATB

Charles Kincaid

Post #744466
« Prev Topic | Next Topic »

Add to briefcase 1234»»»

Permissions Expand / Collapse