CodingStyle

Our code style is wacky but I ask that all contributors follow it. Here's some of the wacky things we do:

• • We put single line if blocks on one line. I like it 'cause its dense.

        if(condition) doSomething();

• • We put blocks that describe what an if() or an else() block to immediately before the block, even if that flows weird with the IDE's best guess at automatically indenting stuff. I like it because I really read the comments before I read the code, and I like to put comments above the code they annotate.

        // condition one is the first option

        if(conditionOne) {

            actionOne();

        // condition two is almost as good as one

        } else if(conditionTwo) {

            actionTwo();

        // everything else goes here

        } else {

            otherAction();

        }

• • We let lines get long. Perhaps 100 columns long. If you need to view 'em on a narrow display or in side-by-side columns or for printing, get your IDE to soft-wrap the lines (ie. no new newline chars). The reason for this is simple. I hate spending time pretty-printing my code to a certain length. One place I've worked has a strict 80 char limit and all the developers there spend all their time pretty-printing code rather than writing it. Glazed Lists is my opportunity to rebel from this.

  • No space between the keyword and the brackets in if(), else(), and while(). James likes to disobey this rule, but don't follow his example. The reason for this one is that when the Glazed Lists project was first started we couldn't decide on the format of if() and else() statements so we held a vote. It ended 1-0 for no space, so that's what we went with. We only use that style today 'cause we want to be consistent with the old code.

  • No anonymous inner classes. This is due to a technical limitation of the tool we use to generate Java 1.4 source code. I like anonymous inner classes, but we make do without 'em.

  • No Java 5 enums, for each, autoboxing for same reason as the previous rule.

  • Spurious use of 'final' is permitted. James loves the final keyword and once told me that if he wasn't already with someone he would marry it. Whenever you see code that uses final everywhere possible, that's James' signature. Kinda like the 'Z' that zorro cuts with his sword. Final is a useful keyword and it prevents bugs. I particularly like it for member variables. For method variables I think it's overboard, but I like to let James have his fun.

  • Sometimes we have too much documentation for a simple piece of code. This is 'cause the way I write code is I write the pseudocode in comments, then I fill in the Java constructs that implements the pseudo code below such comments. It's really helpful for complex methods (see SortedList.listChanged() for examples), but I do it in other places too. Please overlook this, it's the training wheels on my bike that I've gotten used to.

  • Too much use of {@link } and {@inheritDoc}. This is my fault as well. I decided to use {@link } instead of <code> one time and it stuck. Feel free to use {@link } liberally, although I don't mind if you only link the first mention of a particular class or method and leave the rest in plaintext.

  • A do-nothing comment. Usually an empty pair of curly braces is a programmer error - something forgotten to be implemented. I use a comment to make it explicit that is intentional, such as in this particularly horrible program:

       try {

           for(Iterator i = a.iterator(); !b.contains(i.next()); ) {

               // do nothing

           }

           System.out.println("A and B share at least one element");

       } catch(NoSuchElementException e) {

           // do nothing

       }