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 123»»»

Database Commenting Guideline Expand / Collapse
Author
Message
Posted Tuesday, June 6, 2006 11:32 AM
SSC-Enthusiastic

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

Group: General Forum Members
Last Login: 2 days ago @ 12:56 AM
Points: 164, Visits: 191
Comments posted to this topic are about the content posted at http://www.sqlservercentral.com/columnists/sdedhiya/databasecommentingguideline.asp




Regards,
Sachin Dedhia
Post #285374
Posted Tuesday, June 13, 2006 2:46 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Monday, March 2, 2009 3:01 AM
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.
Post #286925
Posted Tuesday, June 13, 2006 6:12 AM
SSC Veteran

SSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC Veteran

Group: General Forum Members
Last Login: Wednesday, May 21, 2014 8:17 AM
Points: 298, Visits: 335

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
Post #286963
Posted Tuesday, June 13, 2006 6:43 AM
Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Wednesday, August 8, 2007 2:25 PM
Points: 53, Visits: 1

It would be nice to have more elaborate examples.

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

Post #286979
Posted Tuesday, June 13, 2006 6:47 AM


Hall of Fame

Hall of FameHall of FameHall of FameHall of FameHall of FameHall of FameHall of FameHall of FameHall of Fame

Group: General Forum Members
Last Login: Yesterday @ 6:11 AM
Points: 3,469, Visits: 1,489

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

Post #286984
Posted Tuesday, June 13, 2006 6:50 AM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Tuesday, December 8, 2009 3:25 AM
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
*/
Post #286987
Posted Tuesday, June 13, 2006 7:06 AM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Wednesday, August 27, 2014 1:07 AM
Points: 2,901, Visits: 1,805
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
Post #286995
Posted Tuesday, June 13, 2006 7:31 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Friday, March 11, 2011 8:04 AM
Points: 12, Visits: 18
"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
Post #287012
Posted Tuesday, June 13, 2006 9:03 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: Wednesday, August 27, 2014 9:58 AM
Points: 886, Visits: 1,545

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!
Post #287067
Posted Tuesday, June 13, 2006 9:54 AM
SSC-Addicted

SSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-Addicted

Group: General Forum Members
Last Login: Tuesday, August 26, 2014 7:20 AM
Points: 495, Visits: 96
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...



Post #287083
« Prev Topic | Next Topic »

Add to briefcase 123»»»

Permissions Expand / Collapse