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.