Database Commenting Guideline
-
If you want to be shackled to your old achievements then don't bother commenting your code.
As long as you work for the organisation it will always be quicker/cheaper to ask you to fix/modify your old code rather than assign it to someone else. Without those comments you will have a hard job making a case for someone else to take it over from you.
From bitter personal experience I know that if you are shackled to old code you don't get to work on the newer sexy stuff.
-
I wanted to include an example for the "Avoid copying and pasting comments" point, however, including the example in the same point would not have had much an impact. Great you identified it. This is usually what happens when you copy paste.
I bet this situation will never arise with you. Happy commenting!
Regards,
Sachin Dedhia -
There are 'n' ways of defining a standard header. For this reason the only mention is about some basic information that CAN to be in there. And it completely depends on you, rather I would say, your team what is and how it is required.
Again for developing a uniform commenting style, all the points mentioned in the article prior to this (based on my experience of 4 years) can contribute.
One point I would like to mention is if these are mutually agreed by the team there are chances one may see some better results.
Regards,
Sachin Dedhia -
If you are writing code, you start commenting your own code. If developers in your team happen to visit your code frequently they will realize the difference.
At times I go to the extent of adding the comments for the code that is frequently visited and written by others (in case I have some spare time).
You never know when your approach will start the next revolution.
Regards,
Sachin Dedhia -
Comments have to be provided however not to the extent that one has to dig for the code. There are couple of points in the article that highlight on maitaining the balance between the code and the comments.
Btw, I appreciate the your way of careful selection of variable name. I do the same.
Regards,
Sachin Dedhia -
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
-
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...
-
Very good article and reviews!
Regards,Yelena Varsha
-
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...
-
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")
-
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
Viewing 11 posts - 16 through 25 (of 25 total)
You must be logged in to reply to this topic. Login to reply