msgbartop
News, views, tips and tricks on Oracle and other fun stuff
msgbarbottom

Comments Do Make a Difference

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.


Filed in Oracle on 15 Aug 06 | Tags:


Reader's Comments

  1. |

    Even better, us a constant with a suitable name :)

    Cheers

    Tim…

  2. |

    Right, constants are very useful in this situation. In fact, I am going to have a separate post about PL/SQL constants soon.

  3. |

    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.

  4. |

    i agree, always if possible use constants and as metioned where the optimizer could benefit comment and do not use them. Karl

  5. |

    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.

  6. |

    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: I do not object to “magic numbers” as long as they are described and documented when used.

  7. |

    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.

  8. |

    Interesting Posts Kristal