good java style: part 2
by thornton rose

introduction
this is the conclusion of a two-part series on java coding style. in good java style: part 1

, i introduced my case for writing java code using good habits, explained why we should care about the way our code looks, and illustrated some general elements of good java style. in this part, i illustrate more elements of good style and bring my case to a conclusion.

source files
there are many ways that a java source file can be organized. here is one that works well:


file header comment (optional).
package declaration.
blank line or other separator.
import statements.
blank line or other separator.
class(es).

example 1. bad file organization.


   package org.rotpad;
   import java.awt.*;
   import javax.swing.event.*;
   import org.javacogs.*;
   import javax.swing.*;
   import java.awt.event.*;
   class foo {
    ...
   }
   public class rotpad extends jframe {
    ...
   }


example 2. good file organization.


   package org.rotpad;
   
   // java classes
   import java.awt.*;
   import java.awt.event.*;
   import javax.swing.*;
   import javax.swing.event.*;
   
   // javacogs classes
   import org.javacogs.*;
   
   /**
    * rotpad is a simple gui application for performing rotation ciphers on plain
    * text.
    *
    * @author thornton rose
    * @version 1.0
    */
   public class rotpad extends jframe {
      ...
   }
   
   //-----------------------------------------------------------------------------
   
   /**
    * foo is ...
    *
    * @author thornton rose
    * @version 1.0
    */
   class foo {
      ...
   }


import statements
a complex class can have a large number of imports, which can get unruly, especially if you prefer to import individual classes instead of whole packages (e.g., java.awt.*). to get a handle on imports, organize them as follows:


java standard classes (java.*).
java extension classes (javax.*).
third-party classes.
application classes.

be sure to comment the third-party and application classes, particularly those that do not have obvious names. use end-of-line comments, or put a comment at the beginning of the section. also, if you really want to be a perfectionist, order each group of imports alphabetically.

example 3. bad import style.


   import java.util.*;
   import javax.swing.*;
   import java.awt.event*;
   import com.gensym.com.*;
   import javax.swing.table.*;
   import com.pv.jfcx.*;
   import java.awt.*;
   import com.melthorn.util.*;


example 4a. good import style.


   import java.awt.*;
   import java.awt.event*;
   import java.util.*;
   import javax.swing.table.*;
   import com.gensym.com.*;     // beanxporter
   import com.pv.jfcx.*;        // protoview
   import com.melthorn.util.*;  // utilities

example 4b. good import style.


   
   // java classes
   import java.awt.*;
   import java.awt.event*;
   import java.util.*;
   import javax.swing.table.*;
                           
   // beanxporter
   import com.gensym.com.*;     
                           
   // protoview gui components
   import com.pv.jfcx.*;
                           
   // application classes
   import com.melthorn.util.*;


classes
organizing a java source file without organizing the classes in it would not gain you much in the way of proper style. here's how to organize the classes in your source files:


javadoc comment or other header comment.
class declaration.
field declarations.
blank line or other separator.
constructors.
blank line or other separator.
methods, except main()

, grouped logically.
blank line or other separator.
inner classes.
blank line or other separator.
main()

.

example 5. bad class style.


   // rotpad -- gui app. for rot ciphering
   public class rotpad extends jframe {
   private static final string transform_rot13    = "rot13";
   private static final string transform_rot13n5  = "rot13n5";
   private static final string transform_rotascii = "rot-ascii";
   
   private void jbinit() throws exception {
      ...
   }
   
   public static final string title   = "rotpad";
   public static final string version = "1.0";
   
   public static void main(string[] args) {
      ...
   }
   
   public rotpad() {
      ...
   }
   
   private jpanel jpanel1 = new jpanel();
   private jpanel jpanel2 = new jpanel();
   private borderlayout borderlayout1 = new borderlayout();
   ...
   }


example 6. good class style.


   /**
    * rotpad is a simple gui application for performing rotation ciphers on plain
    * text.
    *
    * @author thornton rose
    * @version 1.0
 &