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 Wednesday, June 14, 2006 4:18 AM
SSC-Enthusiastic

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

Group: General Forum Members
Last Login: Wednesday, May 26, 2010 10:24 AM
Points: 190, Visits: 202
Its also worth adding what tables are used in the code in the comment header ...e.g. .....

-- TABLES REFERENCED - SERVER.DATABASE.DBO.TABLE1
-- - SERVER.DATABASE.DBO.TABLE2

rather than having to wade through 4 pages of code to see which tables are being used, and where they are located
Post #287284
Posted Wednesday, June 14, 2006 7:11 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Friday, March 11, 2011 8:04 AM
Points: 12, Visits: 18
Great comments, must mean it was a really good article.

A lot of our managers want comments/revision notes so it leaves a kind of DNA trail...developers DON'T want it for the very same reason...
Post #287327
Posted Wednesday, June 14, 2006 4:10 PM
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 @ 9:53 AM
Points: 3,475, Visits: 584
Very good article and reviews!


Regards,
Yelena Varshal

Post #287572
Posted Thursday, June 15, 2006 12:25 PM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Thursday, August 27, 2009 1:10 PM
Points: 16, Visits: 1,987
Just another related thought...

While I totally agree that commenting code is a good thing, I've gotten out of the habit of using the /* method except for at the beginning of a procedure.

Slashes in the middle of a procedure can prohibit you from commenting out a large chunk of a procedure when debugging.

For example - let's say you have a 200 line procedure and something isn't working properly. You realize that commenting out lines 170 through 220 can help pinpoint the problem. The easiest way to do this is to block out those lines by using the /* */ method - but if there are OTHER comments already using that method inside that chunk of code, you have to first replace those with hyphens (pain!!)

I'm waiting for the day when it's possible to debug SQL Server procedures as easily as one can vb code...





Post #287860
Posted Thursday, June 29, 2006 8:51 AM
Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Tuesday, July 28, 2009 8:25 AM
Points: 50, Visits: 99

Two additional commenting thoughts - probably more applicable to "front-end" code, but also somewhat to TSQL:

1) If coding to a design spec, reference the section of the spec explicitly.  Instead of just "this gathers data for the month-end report", say "this gathers data for the month-end report (see section 5.3 of xxxx spec)"

2) If fixing a bug, reference the bug number if applicable (for example:  "PE 1/20/2009 - fix for bug #43 - C-in-C Error")

 

Post #291213
Posted Thursday, June 14, 2007 9:50 PM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Friday, November 14, 2014 6:53 AM
Points: 2,692, Visits: 1,562

Avoid framing block comments.

This sounds not right. We've got very tight change management in place => you cant do as you please once its on production.

i dont find the block comments any harder to maintain. i use it to provide comments on things that has change when it "pass through many hands", with brief comments on the SP's purpose.

SQL developers should have discretionary judgement to know what to be trusted or not when looking at codes vs comment. To me, commenting everywhere in the code makes the readability worse, as some developer puts the code all over the stored procs, making it hard to track which ones are his's/her's.

We put businesses into SPs too, not just technical.



Simon Liew
Microsoft Certified Master: SQL Server 2008
Post #374102
« Prev Topic | Next Topic »

Add to briefcase «««123

Permissions Expand / Collapse