Friday, August 21, 2009

Writing Maintainable Code

The last few years I've inherited quite a bit of code. The vast majority of it reads terribly.

I get newbies; those who have yet to find their style. Those that I run into I highly encourage to find a style and stick with it...even if the commas are in the front of the line. Of course I wish my style would be the standard. Wait a minute, it already is. Check out this snippet from the Official Oracle documentation:



Let me live in my own fantasy world...

What about the rest though? A friend recently told me he thinks it takes about 2 years for someone to develop their own distinctive style. So why doesn't it seem to happen? Or, do I just see all newbie code?

I doubt that's the case.

I try to write code so that it is readable. Others may not like my style, but it is consistent. A former colleague once said that my code (a 5,000 line ETL package) read very easily. It had a natural flow to it. That was one of the best compliments I have ever received. The point is, I write code with the assumption that someone else will (have to) read it.

I find myself in SQL*Plus, ad-hoc queries, writing them the way I would if I were to check it into source control.
SELECT OWNER, TABLE_NAME FROM DBA_TABLES
...that's pretty rare. I find myself backspacing to fix it
SELECT owner, table_name
FROM dba_tables
That might not be the best example (I have a script for that anyway), but you get the point.

"Practice like you play" is a common sports phrase. Perhaps that's why I write ad-hoc queries in that fashion.

I would offer tips, but that would just lead me back to style. I don't want to force people into using my style (that's a lie, but I accept that I am not Supreme Ruler of Code Style), I just want them to choose.

At a minimum, run your code through one of the various code formatters. Toad has one, SQL Developer has one, I think most tools have one. You can even set them up to match your personal preferences (which should align perfectly with mine).

When asking for help from someone else, don't use the default font in your email client (unless your a plain text email person), highlight the code and put it in Courier New. Please.

Finally, write your code as if someone else has to read it!
at

5 comments:

  1. Jeff MossAugust 21, 2009 at 3:34 AM

    ...just couldn't let the "...even if it has commas at the front" comment go by without saying that's what I do and I hate it when I see anyone doing otherwise...we all like our own style and mine is commas at the front.

    As you say though...as long as you have a standard and the code is consistent to that standard, then it will at least be readable and maintainable.

    Cheers
    Jeff

    ReplyDelete
  2. DomBrooksAugust 21, 2009 at 4:54 AM

    I second Jeff's support for commas at the front.

    Your commas-at-the-end-thinking is clearly insanity and/or of a communist leaning.

    I don't trust autoformatters - never found one that can cope with all my idiosyncracies.

    I prefer to take ten times longer hand crafting all code and spacing to my (b)anal specifications.

    You can normally export these preferences from these tools - have you done this and published saying "use this or die"?

    ReplyDelete
  3. hillbillyToadAugust 21, 2009 at 8:24 AM

    Toad's formatter let's you choose the leading or trailing commas, so you can fix/break your friends code at will :)

    ReplyDelete
  4. oraclenerdAugust 21, 2009 at 9:59 AM

    @jeff

    Yeah, I was targeting you. I've seen your examples for far too long. I have this really cool FF plugin that reformats those sites with SQL examples where the commas are in front, to the correct way. :)

    ReplyDelete
  5. oraclenerdAugust 21, 2009 at 10:02 AM

    @dom

    I think we've had this conversation before.

    I'm with you on the hand-coding piece. I like modeling tools, but I refuse to let them auto-generate the DDL.

    I've tried to configure SQL Developer's formatter to match my style...but can't quite get it to work.

    Spacing.
    Hah! I'll spend way too much time doing the same. I'm starting to automate it through various search and replace actions though.

    Communist Leaning.
    That's good. I was thinking the same exact thing about those who practice the comments in front. :)

    ReplyDelete