Xj3D Coding Standards

In order to facilitate a large group of people working on this codebase we will need to enforce a set of coding standards. So when submitting code for Xj3D we ask that you follow these conventions. These standards are in place in order to keep the code maintainable. There's half a million lines of code in the core toolkit and thousands of users. The codebase is now over 7 years old. These standards are to ensure that we can continue to have a long-term maintainable codebase and not follow the fad de jour of Java.

The golden rule is to develop this code for others, not yourself. Nobody owns any particular piece of code. No-one does. Anyone can edit any part of the codebase. Follow and copy the footsteps of those that have gone before you.


Formatting

File Structure

Naming Conventions

Generally follow Java API naming conventions. Be descriptive, not terse. The name should reflect its use.

Specific conventions we use internally for interfaces:

There are more than this. Check each of the section-specific documents for further details.

Commenting

It's the law in this country!
Code without comments is typically rewritten as no-one knows what it does. Code submission without comments will be rejected. Overly verbose commenting is preferred over simple three word summaries.

We use JavaDoc to generate documentation so please use its conventions. All class variables should have a descriptive comment. Methods should define their behavior, document their parameters and what exceptions can be generated. In general, we expect that a method declaration should include a simple summary and then description of any significant pre and post conditions, or expectations of the given parameters. ie, if a null value is passed in for an array reference, will this cause a crash, NPE or explicitly used to clear the value?

JDK and external libraries

Xj3D has to run on a very wide number of platforms. Expect that we will require code to run on the previous generation to the current JDK version. Right now, that means we require code (and thus libraries used) to be able to run on a JDK 1.4-class JVM and JRE set of libraries.


[ Xj3D Homepage | Xj3D @ Web3d | Screenshots | Dev docs | Dev Releases | Contributors | Getting Started ]
Last updated: $Date: 2005-02-04 22:17:38 $