Writing Maintainable Code
-
ReadyStatus = ( ReadyStatus = False )
So should this be documented, or rewritten?
Mattie
-
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
-
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.
-
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/
-
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
-
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.
-
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
-
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
-
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
-
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.Change is inevitable... Change for the better is not.
Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally) -
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.Change is inevitable... Change for the better is not.
Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally) -
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
-
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.Change is inevitable... Change for the better is not.
Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally) -
I also agree, that you must write SQL code maintainable. But NOT on the way they describe in this article. If you check VB.NET or C# developers, they all write in good maintainable code. If they use SQL, then it is an disaster. I have some good samples:
When you use columns in a select statement, place the comma at firtst. Now you can easely comment a column:
SELECT ColumnA
, ColumnB
-- , ColumnC
FROM TABLE1 WITH (NOLOCK)
WHERE STATEMENT1 = @p_PARAMETER
AND STATEMENT2 = @l_PARAMETER
I also places all columnnames on the same place and all signs and parameters. Now you can easily read the code.
-
Curious... if you like the way it's done in .Net or C#, why didn't you do it that way?
--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.Change is inevitable... Change for the better is not.
Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)
Viewing 15 posts - 16 through 30 (of 35 total)
You must be logged in to reply to this topic. Login to reply