SQL Clone
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Database Commenting Guideline


Database Commenting Guideline

Author
Message
Patrick Folan
Patrick Folan
SSC Veteran
SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)SSC Veteran (204 reputation)

Group: General Forum Members
Points: 204 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
Glen Potter
Glen Potter
SSC Rookie
SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)SSC Rookie (32 reputation)

Group: General Forum Members
Points: 32 Visits: 23
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...
Yelena Varshal
Yelena Varshal
SSCarpal Tunnel
SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)SSCarpal Tunnel (4.6K reputation)

Group: General Forum Members
Points: 4616 Visits: 595
Very good article and reviews!


Regards,
Yelena Varshal

CindyK
CindyK
Grasshopper
Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)Grasshopper (22 reputation)

Group: General Forum Members
Points: 22 Visits: 1987
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...



Paul E
Paul E
Valued Member
Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)Valued Member (58 reputation)

Group: General Forum Members
Points: 58 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")


SimonLiew
SimonLiew
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: 3735 Visits: 1810

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