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 12:56 PM
Right there with Babe

Right there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with Babe

Group: General Forum Members
Last Login: Friday, January 17, 2014 1:22 PM
Points: 727, Visits: 265

Another good example of proper usage of comments within code is to look at some of the system stored procedures.  In the MS world, try looking at sp_get_composite_job_info located in msdb.  I was just in there today trying to gather some meta data of the jobs on the server.  I have learned considerably from reviewing these procs, and the comments are extremely helpful.

- Paul

 



- Paul

http://paulpaivasql.blogspot.com/
Post #300110
Posted Monday, August 7, 2006 1:38 PM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Wednesday, October 15, 2014 11:05 AM
Points: 2,636, Visits: 789

Tom,

I'm not sure I agree with the concept that the amount of typing should control how code is written.  After twenty years of programming, I've realized that you generally pay dearly when doing maintenance for shortcuts taken in development.  As one of my professors once asked, 'if you don't have time to do it right, how can you have time to do it over?'.

Mattie




Post #300121
Posted Monday, August 7, 2006 2:16 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

Mattie,

My comment was in regard to the :

ReadyStatus = ( ReadyStatus = False )

If it took 10 lines of code to do the equivalent, and the above is correct, you shouldn't be adding an extra 9 lines of code because it may not be apparent to a junior programmer.  This would handicap you greatly if you cannot use advanced features of the language.  As a twenty year vet, I mostly see the opposite, where a junior coder did 10 lines of code where there is already a built in function that did the same thing in 1 line.

 

 

 

Post #300133
Posted Monday, August 7, 2006 2:58 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: Thursday, February 6, 2014 12:59 PM
Points: 801, Visits: 1,962

Mattie,

We are of the same mind.  I have seen white space reducers for PERL and C++.  This all comes from the days when we were storing source code on flippies (You remember: Floppies that you notched so that you could use bothe sides).

Then there were COBOL programmers paid by the line.  This yielded the one word per line junk.

VB.Net makes my code pretty.  The auto indent helps me spot logic errors before I even try to single step.  Go to the line above a function definition and type three tick marks (''').  Instant XML documentation.  Just fill in the blanks.  I can look at the object browser and not have to open the code to find the right function.  (Hey. Subs are functions that return Void)

Comment vs Not Comment.  I vote comment.  Your comments should be meaningful.  Function UpdateOrderHistory(ByVal OrderNumber AS Integer) as Boolean.

' This function updates the order history.

My boss said, "Well, no sh**!  I thought it might make coffee or something."

 



ATB

Charles Kincaid

Post #300141
Posted Monday, August 7, 2006 3:31 PM


Mr or Mrs. 500

Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500

Group: General Forum Members
Last Login: Tuesday, June 21, 2011 10:03 AM
Points: 577, Visits: 102
You'd actually want your comment to say that you are updating ALL the employee first and last names to the variable value. That would be an interesting comment! Just teasing...

Signature is NULL
Post #300148
Posted Monday, August 7, 2006 4:15 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: Thursday, February 6, 2014 12:59 PM
Points: 801, Visits: 1,962

Oh, it may not be that funny.

_sql = "UPDATE Inventory SET QOH = QOH + " & CSTR(ReciptQuantity)

Found this in production code.  Customer wondered why his inventory was "over stated".

 



ATB

Charles Kincaid

Post #300156
Posted Monday, August 7, 2006 7:58 PM


SSC-Dedicated

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

Group: General Forum Members
Last Login: Today @ 12:09 AM
Points: 35,348, Visits: 31,886

quote

1801  --Bundled Services, not including VOIP

your documentation is out of date, and the code hasn't even been touched

Mattie,

That might be true except for one thing (I believe this was one of your previous good points, as well)... the code is in a proc called ApplyAdjToPOTS.  On the outside chance that someone doesn't know what "POTS" is (an industry standard acronym), we put it in the header of the code... "POTS: Plain Old Telephone System".  We have totally separate systems to drive Wireless, VOIP, and a couple of other goodies.



--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #300176
Posted Monday, August 7, 2006 8:16 PM


SSC-Dedicated

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

Group: General Forum Members
Last Login: Today @ 12:09 AM
Points: 35,348, Visits: 31,886

quote

I will also now shamelssly plug my SQL PROGRAMMING STYLE book that deals with these issues

Shameless or not, I'm going to have to get a copy of that one... thanks for the tip, Joe...



--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #300178
Posted Monday, August 7, 2006 11:04 PM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Wednesday, September 21, 2011 6:35 AM
Points: 3, Visits: 10
meaningless comments!!!

none of those comments are required...they can be derived from reading the code...if you cant do that then you shouldnt be any where near the code!

the only comments that should be in any program are those that document WHY something was done
Post #300183
Posted Tuesday, August 8, 2006 5:04 AM


SSC-Dedicated

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

Group: General Forum Members
Last Login: Today @ 12:09 AM
Points: 35,348, Visits: 31,886

The point is, Mark, instead of having to read through the code to find what you want, you only have to lightly scim through the comments to find out what a section of code does and WHY it was written.  If you are totally unfamiliar with the code (someone else wrote it) and you've been assigned to do a light mod to the code, it can save you a bit of time.

You can read code... without looking back at JT's code, WHAT does this do?  You have 3 seconds, my friend because your boss is standing over your shoulder, knows you can read code because you've been bragging all day that "if you cant do that then you shouldnt be any where near the code", and expects you to find and fix a problem while he or she is waiting... yes, yes... anyone worth their salt can read this and figure out HOW it's doing something but you have to study it for more than 3 seconds to figure out WHY it's doing it...

    SELECT NVL(c.data_type_cd, 'STRING'),
           c.value_txt,
           c.value_dt,
           c.value_nbr
      INTO v_data_type_cd,
           v_value_txt,
           v_value_dt,
           v_value_nbr
      FROM example.idt_constant c
     WHERE c.constant_nm = p_constant_nm
       AND c.site_cd = p_site_cd;

Now, go back and look at JT's code and you'll find the comment that saves so much time...

    /* found constant, determine data type */

The point is, Yes, if you can't read code, I agree, you probably shouldn't be anywhere near the code.  If you can't eventually figure out "why" (what the purpose of) some undocumented code was written, I agree... you shouldn't be near it.  But, simple little sprinklings of good comments even on "obvious" code is a real time saver when troubleshooting.   For non-obvious, complicated, or "tricky" code, you will need more substantial comments.

Then, there are QA people... they are NOT necessarily people who have a deep understanding of how to read code but they do need to be able to quickly map out what a proc is supposed to do so they can setup a test case to figure out if the code actually did what it's supposed to especially if it writes to a table.  Simple but well written comments can and do save QA people huge amounts of time.



--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #300237
« Prev Topic | Next Topic »

Add to briefcase «««1234»»

Permissions Expand / Collapse