Title: Java Style & Idioms

Name: code layout

Rationale: There is no one "true" way to layout Java code. There are two common styles.

Advantages: A consistent layout is useful for maintenance purposes. It can also make intentions clear.

Disadvantages: Can be extremely religious!

Description:

The most idiomatic Java code layout style is that used by JavaSoft. It is generally used in the literature. This layout style typically has the form:

    public class Test {
        public static void main(String[] args) {
            try {
                if (args.length == 0) {
                    System.err.println("Usage: Test args");
                } else {
                    for (int i=0 ; i < args.length ; ++i) {
                         System.out.println("["+i+"]= "+args[i]);
                    }
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }

I think this style is fairly similar to "classic" K&R. I don't like this style. I find it slightly "cramped". However, it does allow you to get more code on the screen or printed page. I prefer the matching braces idiom. So the above example with matching braces would like so:

    public class Test
    {
        public static void main(String[] args)
        {
            try
            {
                if (args.length == 0)
                {
                    System.err.println("Usage: Test args");
                }
                else
                {
                    for (int i=0 ; i < args.length ; ++i)
                    {
                         System.out.println("["+i+"]= "+args[i]);
                    }
                }
            }
            catch (Exception e)
            {
                e.printStackTrace();
            }
        }
    }

I think this style is more pleasant to read. Obviously it reduces the amount of code you get on the screen or printed page - but this does allow one more space to make notes! Another common habit that I have come across is the use of tabs for each indent level. Developers then define the size of a tab to give the indentation they prefer (e.g. 2,3,4,...). In most development environments today this should be a perfectly acceptable solution.

The idiom is that you DON'T have to layout your code in the JavaSoft manner (unless you work for them, of course ). The only real requirement is that your layout is consistent. I just happen to like my code to be "pretty" too :-)

Hopefully, Java indent/pretty printers will mean that everybody can have code in their favourite style. A really cool approach would be to have an indent/pretty printer tool between the IDE/editor and the source control system.

On checking out the IDE/editor receives the code in the programmer's preferred style. On checking in the code is formatted to the "company" style so that all differences are consistent. Then everybody would happy!

Name: finalizers are evil

Rationale: Avoid finalizers if you can because they might not do what you expected or hoped for!

Advantages: You'll sleep easier at night.

Disadvantages: None.

Description:

Plenty of Java programmers think that finalizers are Java's equivalent of C++ destructors. It is a bit of an eye opener to discover that this is (generally) not the case!

If you read the Java Language Specification section 20.1.11 you get the idea that using a finalizer for object cleanup is not unusual. It states "the usual purpose of finalize is to perform cleanup actions before the object is irrevocably discarded".

So a typical class attempting to use this behaviour would look like:

    public class SomeClass
    {
        public SomeClass()
        {
            // constructor
        }
        
        protected void finalize() throws Throwable
        {
            // destructor!?
        }
    }

However, the default behaviour for the JDK1.1 JVM is NOT to run finalizers on exit of the VM. So it is entirely possible that one's application might perform a complete run without a finalizer having been executed! In JDK1.1 the class method runFinalizersOnExit was added to java.lang.System to allow the programmer to specify that finalizers should be run on exit of the VM. So does this mean that it is now safe to use finalizers? Nope! Because even if you do System.runFinalizersOnExit(true) at the start of your application and then exit the application with a non zero status (e.g. System.exit(1)) at some point during the execution then the finalizers are not executed!

The problem becomes slightly worse under JDK1.2! Under this JDK version runFinalizersOnExit has been deprecated. This is due to problems arising when finalizers were being called on live objects when the JVM exited [BUG:4119554]! Programmers have naturally assumed that finalizers would be called on a "dead" object during garbage collection.

So what's the idiom? Realising that finalizers are NOT destructors! Trying to avoid a dependency on finalizers that may never execute. Having a "close" method (as do InputStream/OutputStream or JDBC ResultSet) is a way of avoiding an unnecessary dependence on finalizer methods. It is likely that JavaSoft will introduce an "onExit" mechanism in a future JDK (i.e. post JDK 1.2!). This will then fix the calling finalizers on live objects problem.