Development Conventions

If you will be contributing any code to the JME project, you need to conform to some conventions to facilitate efficient code sharing and consistency.

• Use ONLY letters, digits, dots, pluses, hypens, underscores for file and directory names that you commit to the repository. Different products and people use jME with all sorts of tools and scripts. Spaces or any other unusual characters will make unnecessary headaches for people.

• Name new files with the standard, lower-case filename extension for that file type. For example, name PNG files like “file.png”, not “file.ping” or “file.PNG”. Don't add files without any extension (e.g. “readme.txt”, “script.sh”, “script.bash”, not “README”, “script”). However, directories should have no extension except for specific justified cases.

• If committing to JME 2.x, use a Subversion config file to enforce the correct file properties for the files that you add. (Until I can afford the time to properly document it in the User Guide or Wiki, please see this Forum Topic.

• The only way that text files (including .java files) will look as intended in all situations (web browsers, forum entries, IDEs, and editors) is to use spaces instead of tabs to indent code. Set your editor or IDE to expand tab keystrokes into spaces. Most developers prefer 2-spaces-per-tab for XML and HTML code, and 4-spaces-per-tab for everything else.
  • Eclipse users (recent distributions): Set for .java files with the ”Spaces only” setting of Tab policy at Preferences / Java / Code Style / Formatter, in the first tab (“Indentation”); and with the ”Insert spaces for tabs” checkbox at Preferences / Editors / Texteditors for other file types.
  • Vim users just ”set expandtab” in your .vimrc, _vimrc, etc. With expandtab mode set, you can also convert all existing tab characters in your current document by just running ”:retab”.
  • Files containing tab characters can easily be updated with the standard UNIX utility program ”expand”. You will normally want to add the ”-t 4” or ”-t 2” switch, since expand defaults to expanding tabs to 8-character stops.

• If you add any non-ASCII characters to *.java files, make sure that your editor is using UTF-8 encoding.¹⁾

• If you add any non-ASCII characters to *.properties files, make sure that your editor is using ISO-8859-1 encoding (unicode escape codes can be used for characters not handled by ISO-8859-1).²⁾

• If you put log and it has arguments, make sure that you don't concatenate Strings but use log() with var args. For example

      logger.info("Child "+child.getName()+" attached to this node "+getName());

  would be

      logger.log(Level.INFO, "Child {0} attached to this node {1}", new String[] {child.getName(), getName()});

  
  Do not put an identifier for the class, method, thread, or a time stamp in the message, because these fields can be added automatically with logger runtime settings. TIPS: Variable params indexes are zero-based, and single-quotes/apostrophes must be doubled (similar to in SQL).

• Use interfaces instead of implementations where they are available. This can often be applied with J2SE collections. For example, except in special circumstances, your method signatures should specify param types like Map or SortedMap, not HashMap or TreeMap. In the same way, when instantiating objects with interfaces, use interface references unless you need an implementation-specific method (which you should try to avoid). Example:

     Map<Integer, String> myMap = new HashMap<Integer, String>()

• Don't include the current runtime or coded class name in toString() implementations. If a using developer wants a class name String, that is what Class.getName() is for, so they should use getClass().getName() or X.class.getName().