World Wind Multi-Platform Design and Coding Guidelines

General

• Read the World Wind API's Overview section for a description of World Wind architecture, design and usage. Read the overview pages of each World Wind package for descriptions of those. These descriptions contain critical information that is not repeated elsewhere. Everyone working on World Wind code must read them before using or modifying the code. If they are not read, mistakes will be made; that is certain.
• The project's development IDE is IntelliJ IDEA. The IDEA configuration files for this project are checked in to the code repopsitory. They define within them global and local library links, formatting rules, etc.
• Most major classes need a no-argument constructor so that the declarative instantiation mechanism can work. WW objects should avoid constructors with arguments so that they can be created genericly by name. This means they should self-configure if at all possible, drawing their parameterized info from Configuration. They should also contain an interface to set the configuration details programmatically.
• In order to make it clear where a name is defined, use fully qualified method and class names for all but those things defined in the same package or a sub-package. For gov.nasa.worldwind.* packages, it's okay to import the gov.nasa.worldwind package. It's also okay to import the JOGL names if they are used a lot in a file. But in general, there should not be any import statements for any other than JOGL or worldwind packages.
• Make field and variable names clear and easy to read. Don't label them with "my" or "m_" or some other goofy notation. Within a class refer to all member fields with "this" at every use. E.g., this.tileCount.
• The buffers one must use to pass arrays of info to JOGL must have their byte order set to that of the machine they're used on. Call nativeByteOrder() on NIO buffers when you deal with them, use the methods in com.sun.opengl.util.BufferUtil.
• Design and document for inheritance or disallow it. Make most classes final and most methods of extensible classes final. See the book Effective Java by Joshua Bloch if you're interested in the background on this rule.
• Favor immutability (all fields final), especially in classes representing some small entity, like a Point or Vector. Immutable classes are fully thread safe and generally less error prone.
• Don't worry too much about frequent memory allocations. Jave 5 is now so optimized for this that allocating an object on the heap has similar performance to allocating it on the stack, and this includes the cost of garbage collection.
• World Wind requires a larger heap size than the JVM default. Use the JVM argument -Xmx512m (at least) when running World Wind.
• Configuration items typically have two values and thus two attribute names: a DEFAULT value that is used if not overridden, and a non-default value that can be set programmatically (in Configuration) to a current value without losing the ability to recover the default value.
• Classes such as BasicCache, BasicFileCache and the logger are effectively singletons but they are not defined in their class definition as such. Their singleton nature comes from their 1:1 association with the truly singleton WorldWind class, which provides access to instances of these "singleton" classes.

Exceptions

• WW objects running in the Main thread pass exceptions through to the application unless there's good reactive/corrective behavior that can be applied within WW.
• Log any exceptions prior to throwing them. Use the same message for the log as for the exception.
• Ensure all exception messages are generated using the i18n method details below.
• Public methods validate their arguments and throw the appropriate exception, typically InvalidArgument. Identifying the exception message the parameter name and the problem -- null, out of range, etc.
• In all cases of Exception, evaluate whether there's a good reactive/corrective action to apply before deciding to pass the exception up the stack. If there is one, apply it and don't forward the exception. Also log a message if you think the application or the user could benefit from the information or know more about why whatever they were doing didn't work as expected.
• In Retriever threads, do not catch Throwable. Catch and react to Exception if there's a good reactive/corrective behavior toapply, otherwise allow them to pass up the stack. Retriever threads should have an uncaught Exception handler specified for the thread. The method should log the Exception or Throwable and then return.
• Private methods whose calling client can't be trusted validate their arguments and throw an appropriate exception.
• Catch exceptions from protected methods called by the super-class.
• The audience for exceptions is not just the user or the client program, but the application or World Wind developer. Throw exceptions that would let them know immediately that they're using faulty logic or data.

Logging

• Logging using java.util.logging has the nice feature of capturing the class and method name at the site of the logging call. That's why there is the common idiom of create message, log message, throw exception. Wrapping these three actions in some utility method would lose the class and method-name feature.
• Log all exceptional conditions before rethrowing or throwing a new exception.
• Ensure all logging uses i18n messages as detailed below.
• Use level FINE for things that prevent the intended action,e.g., file can't be written. Use level FINER for things that don't stop the action but seem exceptional, e.g., a file was retrieved or written redundantly. Use level FINEST for simple notifications. Use FINER for method traces. Using the "FINE"series prevents screen display of these when the default JAVA logging settings are used. Since we're a component, we don't communicate such things directly to the application's user; the application does.

Concurrency

• Use collection classes from the java.util.concurrent package if there's any chance at all that the collection may be accessed from multiple threads. (It's rare that this is not the case.)
• Except for simple atomic variables (but not long or double) the safest way to manage multi-thread access is through the blocking queue classes of java.util.concurrent.

Documentation

• Use the appropriate Ant target to generate javadoc API documentation. Do not use the IDEA Tools command because it's not configured appropriately, only the Ant targets are.
• All public and protected classes, methods and fields should be commented for javadoc documentation generation.
• Descriptions of classes, methods, etc. should start with a capital letter. Parameter descriptions and return-value description should start with a lower-case letter.
• If a class overrides methods from {@link Object} such as toString() and equals(), their behavior for the specific class should be described. For equals() that would be the fields compared. For toString() that would be the representation returned.
• Use links liberally. They help the reader get to information fast.

Code Formatting

• Use the code formatting rules specified in WorldWind.ipr. They are in the project file under (Settings --> Project Settings --> Project Code Style). To apply them, simply use Code --> Auto-indent Lines. You can also just check the box at Subversion check-in time and the formatting will be applied before check-in. Be sure the formatting rules are not overridden in your IDEA workspace.
• Set up IDEA to automatically place the standard project header in newly created files by putting the following as the File Header in the Includes tab of IDEA in the File Templates dialog:
  
/* Copyright (C) 2001, 2006 United States Government as represented by
the Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
*/
package ${PACKAGE_NAME};

/**
* @author ${USER}
* @version $Id$
*/

  Then remove the package name property from first line of the Class and Interface items of the Templates tab in the File Templates dialog. (The package name is in the "include" now, so it gets inserted after the copyright.) Test it out by creating a dummy class. Unfortunately this set-up is a personal configuration in IDEA, not project specific.

• When creating a new file, the Id keyword has to be explicitly set via Version Control --> Set Property --> Property name: svn:keywords, and the term Id included in the text box. If the property is not included in this list then Subversion doesnŐt replace the property string when updating the file.

Internationalization (i18n)

• String "constants" are stored in separate resource files (e.g. ErrorStrings.properties). These files must end in ".properties" and must be stored in the src directory. Strings are stored with the format:  packageOfClass.className.nameOfString=value of the string
• Access the string constants by using the following pattern:  (e.g. WorldWind.retrieveErrMsg("myPackage.myClass.targetStringName");).

Books

• Core Java, Horstmann & Cornell, Volumes 1 and 2, Prentice Hall. Be sure to get the editions covering J2SE 5.
• The Java Programming Language, Arnold & Gosling, Addison Wesley. Be sure to get the most recent edition covering Java 5.
• Effective Java, Bloch, Addison Wesley.
• Java Threads, Oaks & Wong, OŐReilly
• Java Cookbook, Darwin, OŐReilly
• OpenGL Programming Guide, Shreiner & Woo & et al, Addison Wesley. Be sure to get the version covering OpenGL 2.0, which is currently the Fifth Edition.
• Beginning OpenGL Game Programming, Astle & Hawkins, Thomson.
• More OpenGL Game Programming, Astle (Editor), Thomson.
• Mathematics for 3D Game Programming & Computer Graphics, Lengyel, Charles River Media. Be sure to get the Second (or later if there is one) edition.
• 3D Math Primer for Graphics and Game Development, Dunn and Parberry, Wordware.