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


Writing Maintainable Code


Writing Maintainable Code

Author
Message
Paul Paiva
Paul Paiva
Right there with Babe
Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)Right there with Babe (737 reputation)

Group: General Forum Members
Points: 737 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/
MattieNH
MattieNH
SSCrazy
SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)SSCrazy (3K reputation)

Group: General Forum Members
Points: 2953 Visits: 901

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





Tom Erwine
Tom Erwine
SSC-Addicted
SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)SSC-Addicted (402 reputation)

Group: General Forum Members
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.

 

 

 


Charles Kincaid
Charles Kincaid
Ten Centuries
Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)

Group: General Forum Members
Points: 1041 Visits: 2383

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

 



ATBCharles Kincaid
Calvin Lawson
Calvin Lawson
Mr or Mrs. 500
Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)Mr or Mrs. 500 (582 reputation)

Group: General Forum Members
Points: 582 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
Charles Kincaid
Charles Kincaid
Ten Centuries
Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)Ten Centuries (1K reputation)

Group: General Forum Members
Points: 1041 Visits: 2383

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

 



ATBCharles Kincaid
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44974 Visits: 39866

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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44974 Visits: 39866

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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Kiwi_Mark_LFC
Kiwi_Mark_LFC
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: 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
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44974 Visits: 39866

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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
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