When I was reviewing PL/SQL code written by a fellow developer, trying to understand what it does, I came across the following code snippet:
IF org_rec.planning_make_buy_code = 2
THEN
IF org_rec.customer_order_enabled_flag = 'Y'
THEN
p_dc1 := v_originating_org;
ELSE
p_dc1 := v_default_shipping_org;
END IF;
END IF;
Now, I can easily guess that the customer_order_enabled_flag can have a value of “Y” or “N” or maybe NULL, but, how am I supposed to know what 2 means in the statement IF org_rec.planning_make_buy_code = 2 ?!
Of course, I can spend time trying to figure out what 2 means. However, had the original author spent a minute or less adding a comment just prior to that IF statement explaining the meaning of that code, It would have saved me time and effort and made the logic a lot clearer:
/* 1 = buy, 2 = make */
IF org_rec.planning_make_buy_code = 2
...
This is a perfect example when commenting your code makes a huge difference.
Related articles:
Tagged pl/sql | Comments Closed | Trackbacks Closed
Even better, us a constant with a suitable name
Cheers
Tim…
August 15th, 2006, at 7:43 am #Right, constants are very useful in this situation. In fact, I am going to have a separate post about PL/SQL constants soon.
August 15th, 2006, at 8:23 am #Beware of constants as they are really variables (or at least they count as bind variables when it comes to SQL), which means you could end up with some unexpected cursor sharing. [Not saying that it is always bad, just that its something to be aware of.]
Also, taken to the extreme it just looks silly. I’ve worked with code that had constants defined for Y and N (eg cv_y := ‘Y’). And then you’ve got to remember whether cv_y is ‘y’ or ‘Y’ as the variables are case insensitive.
August 15th, 2006, at 3:51 pm #i agree,
August 15th, 2006, at 10:26 pm #always if possible use constants and as metioned where the optimizer could benefit comment and do not use them.
Karl
Robert, for some reason, your comment was not posted, however, it was captured in my cocomment. So, here it is:
Robert Vollman:
Did you talk to the original programmer? If so, what did s/he say:
“What are you doing looking at my code?”
“Oh yeah sorry. No big deal though.”
“I had to get this out the door, no time for comments. Just had to get something working.”
“Comments are a maintenance hassle - if I change the code I have to go change all the comments.”
Nothing, because s/he’s long gone.
Eddie:
No, I did not talk to the original programmer because he is on vacation. But most likely, he will say one of the things you mentioned, except maybe “What are you doing looking at my code?”.
I have been guilty with leaving off necessary comments before. I believe it is a matter of habit and good practice.
August 16th, 2006, at 9:45 am #It seems that my spam firewall needs some tuning. Here is Sheeri’s comment (lost in spam):
Sheeri:
Funny, in my organization there’d be a big ruckus about how it should be scalable, and “magic numbers” like those are often put in a database, so descriptive names and other metadata can be attached. Because there’d be ‘make’,'buy’, and then someone would want ‘promised’, and then someone would want ‘almost’ ……
Eddie:
August 18th, 2006, at 3:40 pm #I do not object to “magic numbers” as long as they are described and documented when used.
It takes me less time to develop a fresh application than making heavy modifications to old one written by someone else for the same reason. comments do make difference.
October 18th, 2007, at 10:24 pm #Interesting Posts
September 28th, 2008, at 7:34 pm #Kristal