ORACLENERD: Code Style: General Principles

Code Style: General Principles

Tuesday, October 9, 2007

I have always wanted to put together my personal code style guide. Now that I have a blog, I can do so rather easily.

This will be the first among many that details my approach to coding style. Yes, it is very particular to me. No, I don't expect anyone in their right mind to follow it. Though perhaps someone can use it as a general guideline.

I am fairly fanatical about style.

Parenthesis go on separate lines, always (I'll eventually contradict myself I'm sure). None of this my line starts with a comma crap. My only concession is that it makes commenting out lines easier. Otherwise, I can't stand it. It's ugly to me and I don't like ugly.

Tabs = 2 spaces

CREATE OR REPLACE is the top line followed by the particular object on the second line (I don't know why, it's my style though).

CREATE OR REPLACE
PACKAGE p_package
IS
...

Always put "show errors" at the bottom of procedure/function/package scripts.

Always end your procedure or function with the name after END.

CREATE OR REPLACE
PACKAGE p_package
IS
...
END p_package;
/
show errors

Align SELECT statements left, not right:

Evil


SELECT blah, t.id, s.x
  FROM t, s
 WHERE t.id = s.id
   AND t.x = s.x;

Correct


SELECT 
  blah,
  t.id,
  s.x
FROM 
  t, 
  s
WHERE t.id = s.id
  AND t.x = s.x;

I believe but can't confirm that Toad Formatter is the main perpetrator of this travesty.

Instrumentation. Use lots of it. Home grown or Mr. Kyte's debug routine. You can also use the Oracle supplied package DBMS_APPLICATION_INFO. I have gotten into the habit of using set_session_longops and it helps tremendously in monitoring those pesky long running datawarehouse programs.

Be liberal in your use of spaces: ADD_MONTHS( TRUNC( SYSDATE, 'MONTH' ), 2 )
Capitalize keywords like SELECT, INSERT, UPDATE and DELETE.
Standard functions should also be capitalized.

I'm sure I've got more and I'll add them here as time goes on.

Labels: development, discipline, style

¶ 10/09/2007 09:07:00 PM

Comments:

To be fair, Toad Formatter is fairly flexible as to the preferences you can set up.

Unfortunately, none of those match my personal preferences, which, inevitably, differ from yours.

I'm not convinced whether coding style is an issue or not. I know that I'm stubborn about my preferred style and I find my formatted code much easier to follow than someone else's. That's definitely the most important factor to coding style - readability.

But I'm never sure if I'm just being awkward/stubborn for the sake of it (i.e we all often tend to have a built-in mechanism to defend the way we do things). If I write something from scratch I tend to use my style, if I'm editing something else then I try to adopt the style of the original author.

Maybe we should all get over ourselves, come to an agreement/standard (yuk!) over the way it should be, stick to it, get used to it and then it will be easier for everyone to follow everyone else's code. I get the impression, for example, that the Java community are pretty much agreed on a bog standard style.

Apologies - this is far, far too long a comment on the subject of coding style.

# posted by

DomBrooks : October 10, 2007 at 3:57 AM

I really like the each line starts with a comma convention since

1. as you remark it makes commenting easier

2. it also makes removing/adding columns easier

but the core thing of course is to have such a covention.

# posted by

Niall : October 10, 2007 at 6:30 AM

Obviously you guys get the gist...that this was in fact a personal preference. I had dreams that people would leave nasty comments.

Now that I'm in the team environment, I've learned to bite my tongue and accept other people's ways.

Convention is definitely the goal. It should be my convention! ;)

# posted by

oraclenerd : October 10, 2007 at 10:11 AM

Niall,

I find it much harder to read code where the commas are at the beginning of the line. After all, the comma appears after text in a sentence, not before it!

And code is written once (maybe mucked around with on a couple of later occasions), but it is read lots of times.

I guess you can tell what my personal preference is!

# posted by

Boneist : October 11, 2007 at 5:38 AM

I once was fed up writing "styling guides" for whatever language, including pl/sql. What I came up with is a set of options in TOAD (which we use to write pl/sql, but this could be any source code tool). TOAD (or any similar development tool) has a "code beautifuler". There are also numerous standalone public domain tools that do the same type of work. So rather than imposing a "style of writing code", I imposed a set of rules/options for the code beautifuler, and each developer was requested to filter its code through the beautifuler before submitting to version control. It made life a lot easier for me and my team.
Hope this helps.

# posted by

Pierre : October 11, 2007 at 7:10 AM