Ricebridge Coding Standards

Coding standards are an essential part of developing high quality software. They create a consistent and reliable base for testing, evolving and evaluating all the code that goes into our components. We haven't just thrown together a few methods and classes that seem to work. We pay attention to the details, so that everything comes together to make our components rock solid.

We are making our coding standards publicly available because we want to demonstrate that we take the quality of our work seriously. We stand by what we do and we want you to know that when you use our components, you can be sure that we have nit-picked every detail.

By the way, we do not use Hungarian Notation, which we think is a bit silly and over-the-top. Rather, we use a practical set of prefixes, that show meaning, not type (that's what compilers are for!). This means that you can tell instantly, just by looking, what will happen when you use a variable.

Our conventions are designed as additions and modifications to the standard Java conventions, which we use as the default standard.

Coding Standards

1. Choice of Name
We try to choose names that mean something, even out of context. We usually avoid abbreviations that drop vowels, preferring to use root syllables. In general, names should be fairly short, but with modern auto-completion longer names are also usable.

2. Instance Variables

private String iFoo = "bar";

3. Static Variables

private static String[] sFoo = new String[] {"bar"};

4. Parameters

public void method( String pParam ) {}

4. Local Variables

int foo = 101;

5. Iteration Variables

for( int rowI = 0; rowI < rows.length; rowI++ )

6. Always Use Brackets

if( true ) { doThis(); } 

7. Indent! Indent! Indent!
"Indent according to program flow", Tom said logically. Frankly, incorrect and inconsistent indentation is just not going to cut it. We like to use two spaces, as that gives you more horizontal space. If it's a new code block it gets a new indent, period. And please don't use tabs!

8. Bracket Wars
Well, this one is sure to please. The number one cause of permanent injury among programmers. We've chosen a compromise between the space-wasting bracket-gets-its-own-line-and-indent and the confusing "squash-em-and-see" approach. Basically, if, else, for, while, try, catch and friends should all start on a new line and never have a preceding bracket, like so

if( true ) {
  doThis();
}
else {
  doThat();
}

We think this style highlights the logic of the code and keeps things nicely aligned.

9. Alignment
This is one we picked up from Code Complete and also from The Non-Designer's Design Book. The basic idea is that stuff that goes together should be closer together physically than stuff that isn't, semantically speaking. For example:

private String iFirst  = "bar";
private int    iSecond = 202;

10. Separation
This is the same idea as the last convention, but applied to whitespace between methods and code blocks within methods. Don't jam everything together, space it out and put methods that are related closer to each other than methods that aren't. We tend to separate methods with two lines, and groups of methods with three lines. Inside methods, we tend to use one line to separate logical blocks.

11. Comments
Javadoc comments are absolutely required. Well, we are writing components, and we do sell the source code, so this is part of the product. We tend towards the idea that code should be self-documenting, but an occasional inline comment or two is not going to hurt anybody.

12. Use Common Sense
"First, your return to shore was not part of our negotiations nor our agreement, so I must do nothin'. And secondly, you must be a pirate for the Pirate's Code to apply, and you're not. And thirdly, the Code is more what you'd call "guidelines" than actual rules. Welcome aboard the Black Pearl, Miss Turner."
   Captain Barbossa (Geoffrey Rush), Pirates of the Caribbean

So there you go, that's how we do things. If you have any views on our coding conventions, particularly strongly-held dogmatic ones, we'd love to hear them!