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 ««1234»»»

Writing Maintainable Code Expand / Collapse
Author
Message
Posted Monday, August 7, 2006 9:39 AM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Tuesday, September 9, 2014 9:18 AM
Points: 2,623, Visits: 788

To Joe's point:  I think Jeff's documentation is an excellent example of my point.  When the user decides that

SvcTypeID IN (1,2,3,5,1801)

doesn't mean 

WHERE SvcTypeID IN (1, --Standalone Long Distance
                    2, --800 Service
                    3, --800 Pin

                    5, --Calling Card
                 1801  --Bundled Services
                    )

but instead means

WHERE SvcTypeID IN (1, --Standalone Long Distance
                    2, --800 Service
                    3, --800 Pin

                    5, --Calling Card
                 1801  --Bundled Services, not including VOIP
                    )

your documentation is out of date, and the code hasn't even been touched.  I agree completely that stored procedures need a functional description and a modification history.

And JT, thanks for posting the function, which I couldn't begin to follow (as an Oracle function) without the comments.  That said, there are several things that go back to Pam's point about naming conventions.  The function name example.idt_f_get_constant_dt could be more descriptive, and the count is selected into a value named v_count_nbr, which is pretty generic too.  But Pam made another point, which is to set up a standard, and stick to it.  So if everyone in your shop agrees that dt is the abbreviation to use for date, and the v_ means something to everybody, then that's what's important. 

As long as it's all written down somewhere.

Mattie




Post #300042
Posted Monday, August 7, 2006 10:08 AM
SSC-Addicted

SSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-Addicted

Group: General Forum Members
Last Login: Thursday, March 20, 2014 10:04 AM
Points: 402, Visits: 11

One other area not touched upon that makes code easier to read is:  "When you update code, make sure you do not leave code that is no longer relevent."  For example JT used:

   IF v_data_type_cd = 'STRING' THEN
      v_return_dt := NULL;

    ELSIF v_data_type_cd = 'DATE' THEN
      v_return_dt := v_value_dt;

    ELSIF v_data_type_cd = 'NUMBER' THEN
      v_return_dt := NULL;
 
    ELSE
      v_return_dt := NULL;
 
    END IF;  

instead of

  IF v_data_type_cd = 'DATE' THEN
      v_return_dt := v_value_dt;

    ELSE
      v_return_dt := NULL;
 
    END IF;  

If I had to guess, the original function (or its original intent) returned information about NUMBER and STRING data types.  But I cannot just "guess" when working on code so I need to double check the code to see if I am missing something, which wastes valuable time.

Post #300052
Posted Monday, August 7, 2006 10:22 AM


Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Monday, November 12, 2007 6:32 AM
Points: 62, Visits: 3

Tom,

Good catch!  This function is actually one of 3 versions (_dt, _nbr, and _txt) with a parallel designs.  I.e. they all have the same if/then statement for consistency sake.  But yes, the code could be condensed in this version.

Post #300056
Posted Monday, August 7, 2006 10:30 AM


Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Monday, November 12, 2007 6:32 AM
Points: 62, Visits: 3

Mattie,

Both the function name and the column names use standard abbreviations that are in the standards guide.  We've found it cuts down on the possible ways of naming a column.  For instance first name is always "first_nm" and never "first_name", "FirstName", or "FName".  The function names are a bit tougher to decode, but they're also standardized to be:

idt = application prefix (used for functions, procs, packages, tables, views, etc)
f = function, as opposed to "sp" for procedure or "pkg" for package (oracle group of related functions)
get_constant_dt = verb-noun set to describe what the object does.

The v_ indicates a local variable as opposed to a g_ for global, c_ for constant, or p_ for parameter.  In Oracle it prevents accidently re-using a variable or column name and causing very difficult to locate bugs.

Post #300060
Posted Monday, August 7, 2006 11:35 AM


SSC Eights!

SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!

Group: General Forum Members
Last Login: Thursday, February 6, 2014 12:59 PM
Points: 801, Visits: 1,962

Agreed. But then, "I'm with Jeff on the issue of comments though.  If you *have* to put comments to tell *what* you did, it's either very complex or poorly designed." does not take into account the many cases where we are deling with importing (or mining) data from somebodyelses tables.

We try to use a good naming convention.  We can use my table documentor to extract the table names, column names, and data types.  The tech writers cut and paste this into the system manual and only have to fill in comments in rare occasions.

Then I get the joy of having to go get data from SAP, Great Plains, or J. D. Edwards.  Not so bad.  Next I get an assignment to deal with some home grown system.  Now comments every where!

 



ATB

Charles Kincaid

Post #300081
Posted Monday, August 7, 2006 11:41 AM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Wednesday, April 23, 2014 8:55 AM
Points: 6, Visits: 40
Agree with the comments about 'why'.  Why isn't used to redundantly explain 'what' but why you made certain choices.  It does not explain what the code does, but explains how you decided to default something or why you are choosing some construct that might not be obvious.  Sometimes it might be "the PM said blah blah is ok, but I don't trust that and am handling the possibility by doing xyz". 
Post #300085
Posted Monday, August 7, 2006 11:47 AM


SSC Eights!

SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!

Group: General Forum Members
Last Login: Thursday, February 6, 2014 12:59 PM
Points: 801, Visits: 1,962

Obvious, from reading code?

Try

ReadyStatus = ( ReadyStatus = False )

To an experinced VB programmer it might be appearent but two member of our team could not understand what it did until it was re-written as:

ReadyStatus = NOT(ReadyStatus)



ATB

Charles Kincaid

Post #300087
Posted Monday, August 7, 2006 12:02 PM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Tuesday, September 9, 2014 9:18 AM
Points: 2,623, Visits: 788

 ReadyStatus = ( ReadyStatus = False )

So should this be documented, or rewritten?

Mattie




Post #300096
Posted Monday, August 7, 2006 12:42 PM
SSChasing Mays

SSChasing MaysSSChasing MaysSSChasing MaysSSChasing MaysSSChasing MaysSSChasing MaysSSChasing MaysSSChasing Mays

Group: General Forum Members
Last Login: Yesterday @ 2:32 PM
Points: 607, Visits: 974

Put me on the "comment your code" side of the argument (the "why" can be critical six months down the line); and adding white space for readability, too!

Since I work in multiple languages (starting with COBOL back in '80), the "don't use abbreviations" in names is one area I have to disagree with. 

If we didn't abbreviate, the COBOL names would get totally out of hand, and take up an entire line by themselves.  In my current business, we have standard abbreviations that are used, for instance "Elig" means "Eligibility".  Fortunately it's a "spoken abbreviation" as well - a business standard!  I'll maintain, for the sake of discussion, that as long as an abbreviation is standardized, it's okay to use them in names of variables, stored procedures, functions, or whatever.

In terms of standards, I agree with Pam that they give you a structure, but getting too detailed with them will cause problems.  I worked on a standards committee once where we had a "cross every <T> dot every <I>"  member, and it wasted a whole lot of time.  A basic set of rules that everyone can understand is essential; anything beyond that is superfluous.




Here there be dragons...,

Steph Brown
Post #300108
Posted Monday, August 7, 2006 12:44 PM
SSC-Addicted

SSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-AddictedSSC-Addicted

Group: General Forum Members
Last Login: Thursday, March 20, 2014 10:04 AM
Points: 402, Visits: 11
If it doe not affect speed or resources, I would vote for rewrite since the typing is approximately the same.  If any of these 3 are affected (speed, resource, or much more typing) then keep the same.  As far as documenting, this is where the question of "what is obvious" comes into play.  If too many comments are made for the sake of junior programmers, then the "important" comments get lost.
Post #300109
« Prev Topic | Next Topic »

Add to briefcase ««1234»»»

Permissions Expand / Collapse