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


Database Commenting Guideline


Database Commenting Guideline

Author
Message
Sachin Dedhia
Sachin Dedhia
SSC-Enthusiastic
SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)SSC-Enthusiastic (166 reputation)

Group: General Forum Members
Points: 166 Visits: 218
Comments posted to this topic are about the content posted at http://www.sqlservercentral.com/columnists/sdedhiya/databasecommentingguideline.asp




Regards,
Sachin Dedhia
Dan Sydner
Dan Sydner
Grasshopper
Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)Grasshopper (13 reputation)

Group: General Forum Members
Points: 13 Visits: 10
Develop a standard header for stored procedures, views and user-defined functions. Include details such as a brief description of the object, specification document, author, date created, change history, etc.

Throughout the application, develop and maintain a uniform style of commenting. This improves the readability of the code and represents a professional approach.


It's a shame that neither of these two interesting points get more than a mention.
BobAtDBS
BobAtDBS
Old Hand
Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)Old Hand (304 reputation)

Group: General Forum Members
Points: 304 Visits: 357

The bottom line message in this article is "Comment your code if it's not absolutely clear what you are doing".

I like that. It's what I do. It's what I want my developers to do.




Student of SQL and Golf, Master of Neither
Robert Sterbal
Robert Sterbal
Valued Member
Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)Valued Member (57 reputation)

Group: General Forum Members
Points: 57 Visits: 1

It would be nice to have more elaborate examples.

Sample code commenting style would make a great little web site.


Scott Arendt
Scott Arendt
SSCarpal Tunnel
SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)SSCarpal Tunnel (4K reputation)

Group: General Forum Members
Points: 4048 Visits: 1702

At my current place of employment, over 6 years and 20 developers, there have only been 2 that comment with any regularity.

The first one, who has long since moved on, simply put his name and a creation date in the sproc. But at least I could then go back to him if I had a question.

The other one is me.

Regards,

Scott


Rob Smith-216121
Rob Smith-216121
Forum Newbie
Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)Forum Newbie (7 reputation)

Group: General Forum Members
Points: 7 Visits: 8
I agree, when I look at code the first thing I want to know is what it does, who created it and what it references.

Shame the author didn't follow their own guidelines

Avoid copying and pasting comments.

-- Spearate cooments from comment characters with a white space

/* Spearate cooments from comment characters with a white space */

/*
Spearate cooments from comment characters with a blank line
*/
David.Poole
David.Poole
Hall of Fame
Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)Hall of Fame (3.7K reputation)

Group: General Forum Members
Points: 3708 Visits: 3121
I think it is worth mentioning that both Apex SQLDoc and Innovasys DocumentX use special (and virtually identical) comment tags so that they can suck out the comments and build a compiled help file of your database.

These two products are inexpensive.

Because of what they do the benefit to the individual developer of commenting their code becomes very obvious. The larger the project the more important the comments become.

LinkedIn Profile

Newbie on www.simple-talk.com
Glen Potter
Glen Potter
Grasshopper
Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)Grasshopper (14 reputation)

Group: General Forum Members
Points: 14 Visits: 23
"Avoid framing block comments. It looks attractive initially but is difficult to maintain..."

Not nearly as difficult as trying to maintain code without revision notes of who did what so you can go to them for more info about "why" they changed the code and why "like that".

I have our citation as part of one of the templates we use for stored procs and scripts, so you ctrl+shift+m to populate the info and your form structure is set for you:

IF EXISTS (SELECT name
FROM sysobjects
WHERE name = N''
AND type = 'P')
DROP PROCEDURE
GO

SET QUOTED_IDENTIFIER ON
GO
SET ANSI_NULLS OFF
GO



CREATE PROCEDURE
<@param1, sysname, @p1> = ,
<@param2, sysname, @p2> =
AS
--++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
--STP: procedure_name
--Author:
--Notes:
--Date: current_date
--Rev's
--
--++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

SELECT @p1, @p2

GO
SET QUOTED_IDENTIFIER OFF
GO
SET ANSI_NULLS ON
GO



grant execute on TO PUBLIC

GO
YSLGuru
YSLGuru
SSC Eights!
SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)SSC Eights! (969 reputation)

Group: General Forum Members
Points: 969 Visits: 1659

I've been at my current job for 5+ years and it seems like no one in our development dept ever provides comments in any type of code be it in the program code (we are a software company) or in DB objects such as SP's, UDF's, Triggers, ect. We also have a proprietary scripting that allows our clients to create txt files that contain all teh information needed to create custom reports that can be excuted within our program. We provide a large number of stock versions of these for clients to use. We like the whole scripted report concept much better then reports that are hard coded into the program because it's much easier to update and maintain them. The porblem is there are often no comments in those iether and so clients and those of us in support (where I work) have no idea how many are suppose to work. I have voiced considerbale concern over this to no avail. What finally did me in on this and made me give up was when I asked a senior VP about this one day. I said that while doing so for existing DB objects may be to much to ask, can we at least put in a rule that from this point forward any items added to the schema can not be included in the final product that goes to the client until the developer has added comments to our DDF (Data Dictionary File similiar to an ERD). His response was no and that asking them to do that was asking too much. They had more important things to do then worry about documenting everything they do.

Can anyone share a personal experience that tops that?

Will



Kindest Regards,

Just say No to Facebook!
Keiths123
Keiths123
SSC-Addicted
SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)SSC-Addicted (497 reputation)

Group: General Forum Members
Points: 497 Visits: 114
Another way of doing it is to not comment at all.
(Sorry, I could not be bothered to find the shocked face icon!)

The reasoning is as follows: An inaccurate comment is more dangerous than no comment at all, as developers will read the comment and then not read the code to confirm it is true.

Comments need to be kept up to date as much as any other documentation and sometimes they don't get kept up to date with the code.

The fix for this is to write the code in such a way that the code is self-documenting, so if you need code that gets the mean sales figures for the previous three months you have a function/view/procedure called Previous3MonthsSales. If you have a block of code in a procedure that is hard to understand then take it out into it's own procedure and name the new procedure accordingly.

The only discipline you then have is to ensure your objects only do what they say they do and nothing else, and they do it right! If someone wants Previous3MonthsSales changed to 4 months then create a new code object to do that and name it Previous4MonthsSales.


Just an alternative view...



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