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


Database Commenting Guideline


Database Commenting Guideline

Author
Message
Steve Jones
Steve Jones
SSC-Dedicated
SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)SSC-Dedicated (36K reputation)

Group: Administrators
Points: 36224 Visits: 18751
I saw you make a basic note at the top, then only comment complex, not obvious logic. And then add notes when you change something. Other than that, keep it simple.

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
ScottPletcher
ScottPletcher
Hall of Fame
Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)Hall of Fame (4K reputation)

Group: General Forum Members
Points: 3950 Visits: 6686

What about the overhead of the comments themselves? This if often overlooked. It's my understanding that SQL does load comments (even full-line/multi-line comments) into the proc cache. So lots of comments = lots of extra proc cache space that could be used for something else.

Thus, I prefer carefully chosen variable names with minimal comments on areas that are difficult or obscure. Hopefully at some point SQL will get better internal code and simply drop comments from the code as it is loading the proc cache.



SQL DBA,SQL Server MVP('07, '08, '09)

Prosecutor James Blackburn, in closing argument in the "Fatal Vision" murders trial: "If in the future, you should cry a tear, cry one for them [the murder victims]. If in the future, you should say a prayer, say one for them. And if in the future, you should light a candle, light one for them."
Kenneth Gladden
Kenneth Gladden
SSC Rookie
SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)

Group: General Forum Members
Points: 47 Visits: 37

I think the point was the asterisks on the right edge; over time they no longer line up as in his example. Your example does not use any characters on the right so you are following his recommendation.


Bruce Morrison
Bruce Morrison
Forum Newbie
Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)Forum Newbie (3 reputation)

Group: General Forum Members
Points: 3 Visits: 1

It seems everyones has their own experiences and horror stories. One year a go I joined a company where all the previous developers had walked out in one day. The was no documentation (they never prepared it) and no user manuals. Talk about a struggle.

Some form of documentation is needed to understand the business logic that is being implimented. I tell my team that I'm not planning on leaving soon but I could be hit by a bus crossing the street tonight.

All new development include header comments on who coded the program unit, when it was done, and why it was done. I go a step further and include comments on the arguments, the result set, any return values, as well as constants or configuration values that need to be set. I do this because it make it very easy to share documentation with consultants who are preparing external services for us.

The most critical comments though, are the comments documenting changes.

In the header we include the following:

-- MODIFICATION HISTORY
-- --------------------
-- DEVELOPER: R. B. Morrison
-- DATE: June 13, 2006
-- REF: 20060613
-- COMMENTS: Modififed search criteria to remove the date added and
-- include date modified.

Within the code the following comments are made:

SELECT first_name
, last_name
, address
, city
, state
-- START 20060613
-- , date_added
, date_modified
-- END 20060613
FROM members

Now when we need to find the changes that were made, we use the search tools of Query Analyzer (or what ever tool we are using) to find where the reference number occurs.


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 have read the comments by some advocating less or little to no documentation and I do understand why you feel the way you do but that type of mentality is the wrong type in development. There is no such thing as implied or understood code with anything but the simplest of processes. If you have to choose between providing to little information and too much you should always err on the side of too much. Why? Because when you either document very little or none at all you provide the person that comes after you with no options at all but to guess at what your code does or means. And even in the case of self-evident code it can be easier and a lot quicker to read a quick note from the code's author then to try and go thru their code and decipher what the intent is. Take the case of complex SQL queries which any DB app uses. If you opt to not explain what the query returns and what logic it uses to determine the result set as well as how the criteria work then not only are you placing a burden on those that follow you but you also do your customers and your co-wrkers a grave injustice. As one who works in support and also does some development I can tell you that clients do not like it when we can't explain to them how for example a report works because the reports author didn't bother documenting it. And no you can't just assume that the person(s) who review your code will understand it the way you did. That works only in an ideal world where everyone thinks alike.

If you are too lazy to document your work then for the benefit of the rest of us please find something else to do. As a support tech you are the worse kind of nightmare. Not only are we unable to explain to our clients/users why something works the way it does or doesn't work the way they think it should but you also give the rest of develpment a bad name. When enough of you do this kind of thing it makes everyone look like as if they are either too lazy to document their work or worse they don't document their work because they are not confident or perhaps even competent in their abilities. After all if you don't document your code it's very difficult for some one to say it doesn't work because there's nothing from you in writing indicating how it's suppose to work.



Kindest Regards,

Just say No to Facebook!
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: 3696 Visits: 3120
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.

LinkedIn Profile

Newbie on www.simple-talk.com
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

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

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

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