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


Worst Practice - Bad Comments


Worst Practice - Bad Comments

Author
Message
nmoore
nmoore
SSC Veteran
SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)

Group: General Forum Members
Points: 236 Visits: 173
Is there anyone out there at the other end of the scale. With a live constantly evolving production system with next to no comments and no documentation? Yes I know its 2003 .....

Nigel Moore
======================
nmoore
nmoore
SSC Veteran
SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)SSC Veteran (236 reputation)

Group: General Forum Members
Points: 236 Visits: 173
Any suggestions on the best approach to tackle such a situation if you inherit it?

Nigel Moore
======================
David.Poole
David.Poole
SSCertifiable
SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)

Group: General Forum Members
Points: 7476 Visits: 3282
If it works its obsolete

It depends on the nature of the evolution. If it is constantly trying to implement new stuff then this suggests that you are not able to implement proper change control/testing procedures.

It also suggests that you are dependent on individuals with key knowledge of the system.

I say this because if you work in teams then you simply can't do without good documentation. The team cannot function without knowledge share. Knowledge share includes documentation

Trying to implement good practice retrospectively is hell.

Ideally, you need to get agreement to slow down the evolution and have set release timetables, but you need management to buy into this.

Sell it as
  • Long term reduced cost
  • Improved quality
  • Long term Increase productivity


To use a military analogy, after every advance you need to consolidate your position and make sure that the supply lines do not become over extended and therefore vulnerable.

Think of the supply lines as being the path to bring a new team member up to speed on the system

LinkedIn Profile

Newbie on www.simple-talk.com
Antares686
Antares686
SSChampion
SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)

Group: Moderators
Points: 11418 Visits: 780
Some of the early products are this way. They changed almost everyday depending on who called you and none of the code had documentation or comments so you were left reading it. Some of the older code is still out there without comments but about a year ago we got everyone into the habit of doing comments if no documentation (self documenting). All and all things have gotten much better. It takes me about and 8th the time to figure out what to change to correct most situations and we forced the end users to go thru a project manager who would validate need, time and priority (which priority was the key, no more now stuff). But as David states it is a pain.

I agree with everyone here on comment header blocks with details of who, when and why in them. Maybe MS will move this into SQL like they have done with column and other comments so you don't have to do this but I doubt it.



mattowen
mattowen
SSC Journeyman
SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)SSC Journeyman (84 reputation)

Group: General Forum Members
Points: 84 Visits: 10
Headers are essential. They not only indicate who made a change (provided the author still works with you) but also tie a change to a work order here, allowing you to find the original requirements to see the reasoning behind it.



vyaskn
vyaskn
Valued Member
Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)Valued Member (74 reputation)

Group: General Forum Members
Points: 74 Visits: 8
quote:

So for all those out there who randomly use lower case and upper case and argue that the code works just fine regardless of what you use - refer to Andy Warren's line where he says that neatness contributes to readabilty - & readability finally contributes to maintenance - Just like you wouldn't trash your house with litter, look upon your code the same way - take pride both in it's functionality AND appearance!!!



There's more to it. If you are a vendor and ship your database code to your clients' place, your procedures will fail to run on a case sensitive SQL Server. It is important to be consistent and correct in the usage of case, if you want your code to work at all your client sites.

HTH,
Vyas
http://vyaskn.tripod.com/


HTH,
Vyas
SQL Server MVP
http://vyaskn.tripod.com/
sushila
sushila
Hall of Fame
Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)Hall of Fame (3.5K reputation)

Group: General Forum Members
Points: 3497 Visits: 639
You learn something new every day - since I've never come across a case-sensitive instance of Sql server ever before (limited experience ??) I wasn't even aware that the option to create one existed.

BTW - why would anyone want to create a case-sensitive instance of sql server - at first I thought it could be for a similar reason as declaring an "option explicit" in vb - but that really doesn't make any sense ???







**ASCII stupid question, get a stupid ANSI !!!**
Steve Rosenbach
Steve Rosenbach
SSC Veteran
SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)

Group: General Forum Members
Points: 201 Visits: 206
A very good thread, thanks again Andy!

I do like to include a header, for many of the same reasons others have mentioned. I've included a sample of a typical one I've been using for the past 9 months that's worked out pretty well when either our new developer or I have to go back and look at a procedure.

In light of Andy's article, I think I can start eliminating the name of the procedure in the first line of the comments :-)

I like to include a brief description of what the procedure is for and any "interesting" things going on inside that might not be obvious from a first or second reading.

Then I list any parameters and what they mean or any limitations on them.

I usually list table aliases, and finally, I include a "depends on" section -- but now I'm wondering if I should add a section of what depends on the SP.

I don't put a list of variables, because I try to create variables that are self-explanatory by their names and context and use functions to aid in clarity, such as

SET @Qtr1StartDate = FirstDayOfMonthYearAgoThisMonth(@RunDate)
SET @Qtr2StartDate = DateAdd(qq, 1, FirstDayOfMonthYearAgoThisMonth(@RunDate))

I think I can begin leaving off the "modifications" comments - you guys are right - that's easier and better done via source control.

Best regards,
SteveR


/* **************************************************************************************
spRptDoDByCutoffBasis

Usage: EXEC dbo.spRptDoDByCutoffBasis 42782, '4/11/02', 'S', 'F'

Description: Outputs the PXZX and Units/1000 for the immediate past year
and the previous year, figured from the RunDate parameter.
The FromDate of the immediate past year is 1 year prior to
the first day of the RunDate month. The ToDate of the
immediate past year is the last day of the month preceding
the RunDate. The corresponding parameters for the "LastYear"
dates are 1 year earlier

Parameters: @SavedReportID - PK of record in table WH_SavedReports - used
to provide lists of Bases included, Departments included, etc.
@RunDate - used to calculate From and To dates for immediate past year
and the previous year
@RegularOrSpecialCount - 'R' for PRZX, 'S' for PSZX. Defaults to 'R'
@UseStartOrFinishDate - whether data is grabbed based on Start ('S') or
FinishDate ('F')


Table Aliases: c = WH_1Processes_xxxx
d = WH_ParentCodes
p = WH_Procedures


Depends On: Function dbo.spGetRegularAndSpecialCounts (therefore requires SQL Server 2000 or higher)

By : S. Rosenbach 09/12/2002
Modified : S. Rosenbach 09/23/2002 - added ability to run using either Start or Finish Date
S. Rosenbach 10/03/2002 - modified definition of running as Finish to mean finished by
the Run Date AND Posted by the current date.

*********************************************************************************** */



Steve Rosenbach
Steve Rosenbach
SSC Veteran
SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)SSC Veteran (201 reputation)

Group: General Forum Members
Points: 201 Visits: 206
whoops, talk about a good example of things not retaining original spacing when you cut and paste... my header example lost all of my laborious indentation.

-- SteveR



Andy Warren
Andy Warren
SSChampion
SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)SSChampion (11K reputation)

Group: Moderators
Points: 11433 Visits: 2730
So the consensus is for headers then? Minus indents (Steve R)?

Anyone storing more proc meta data elsewhere? Other than VSS I mean.

Andy
http://www.sqlservercentral.com/columnists/awarren/

Andy
SQLAndy - My Blog!
Connect with me on LinkedIn
Follow me on Twitter
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