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 13, 2006 10:14 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Yesterday @ 5:56 PM
Points: 33,202, Visits: 15,348
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
Post #287089
Posted Tuesday, June 13, 2006 10:26 AM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Yesterday @ 2:25 PM
Points: 2,044, Visits: 3,059

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)
"In America, every man is innocent until proven broke!" Brant Parker
Post #287093
Posted Tuesday, June 13, 2006 10:45 AM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Tuesday, August 26, 2014 6:59 PM
Points: 46, Visits: 32

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.

Post #287103
Posted Tuesday, June 13, 2006 2:03 PM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Tuesday, October 3, 2006 7:20 AM
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.

Post #287151
Posted Tuesday, June 13, 2006 2:50 PM


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 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!
Post #287157
Posted Tuesday, June 13, 2006 4:32 PM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

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

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
Post #287230
Posted Tuesday, June 13, 2006 11:03 PM
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

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
Post #287232
Posted Tuesday, June 13, 2006 11:26 PM
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

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
Post #287238
Posted Tuesday, June 13, 2006 11:41 PM
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 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
Post #287239
« Prev Topic | Next Topic »

Add to briefcase ««123»»

Permissions Expand / Collapse