The Web Graph Database

wiki:Docs/CodingConventions

Coding Conventions

Design conventions

Interfaces, abstract and concrete classes
The JDK, in some places, uses the following pattern of interfaces, abstract and concrete classes: an interface defines the semantics of the new concept, say java.util.List. An abstract class that implements the interface factors out functionality likely to be common among many implementations of the interface, e.g. java.util.AbstractList. Concrete classes inherit from the abstract class and implement the concept using one particular strategy, e.g. java.util.ArrayList. We like this structure and use it frequently. For this to be successful, it is important that application developers use the most abstract interface available to accomplish what they need to accomplish; do not depend on the most specific sub-class as that one is the most likely to change in the future.
Use common code wherever the semantics are the same
InfoGrid makes an attempt to factor out common functionality into separate interfaces classes. For example, the Factory interface is used consistently wherever an object of some type creates instances of some other type. Implementation code is reused either through implementation inheritance or delegation, whichever applies better in the circumstance.
Direct, soft and weak references
A deployed InfoGrid application may have to manage a substantial amount of information. For this to scale, it is paramount to pay attention to garbage collection. InfoGrid uses a liberal sprinkling of java.lang.ref.WeakReference in order to allow unused data objects to be garbage collected.
Error reporting
InfoGrid distinguishes between (a) errors that are only of any interest, and should only ever be seen, by developers with access to log files, and (b) errors that are or may be shown to the end user. For developer-only errors, class-specific loggers are used whose output is log4j-style developer-English. All end-user visible errors are reported by throwing a LocalizedException, which itself, together with its resource file, is responsible for error reporting to the user, taking the right locale into account.
"Net-"
The prefix "Net" generally refers to facilities provided by the Graph Database (Grid) Project?.
Naming
We typically prefer long, expressive names over shorter, more confusing ones. The only abbreviation that it used consistently is "M", which generally indicates a class that is an in-memory implementation of some type.

Low-level conventions

Getters and Setters
InfoGrid generally follows JavaBeans conventions whenever it makes sense. It does not generally use the is prefix for the getters of boolean properties, however.
Avoidance of public constructors
Instead of public constructors, classes generally define a protected constructor with minimal functionality, i.e. only member initialization. This makes it easy to define (similar) constructors in subclasses. In addition, classes offer one or more public static factory methods named create that hold the bulk of the code that otherwise would have to reside in the constructor. In our experience, this creates more maintainable code -- for example, the static factory methods may also return different subclasses without requiring clients to change.
Generics
InfoGrid uses Java 5 generics wherever possible, and attempts to keep the number of lines of code small that suppress warnings.
Factory pattern
Methods named obtainFor generally indicate a factory method. The method may either be a standard factory method, or a smart factory method.
Listeners and weak references
The standard Java literature always adds listeners to event-emitting objects like this: someObject.addPropertyChangeListener( new PropertyChangeListener() { ... } );. The problem with this pattern is that those listener objects will never be garbage collected, which is of course unacceptable for almost all applications. (Shame on you, Java book authors!) In InfoGrid, listener addition methods usually come in three flavors: addDirectXXX, addSoftXXX and addWeakXXX, indicating whether the listener is supposed to be referenced directly, or via a SoftReference or WeakReference.
Class-specific loggers
All classes that have a need to log messages have their own, class-specific logger. In some rare cases, a class may have more than one logger associated with it, to support different use cases for why a developer may increase the verbosity of a particular logger. Classes that don't have any need to log anything (today) don't have a logger. All loggers are declared private and are called log.
Last modified 5 years ago Last modified on 01/19/10 19:32:36