Info on JMRI:
Development tools
Structure
Techniques and Standards
How To
Functional Info
Background Info

JMRI: Recommended Practices

This is page of miscellaneous info and pointers for JMRI developers.

Class Library Preferences

Code Format

The Java recommendations for names, formatting, etc are really useful. If you find that you can't read a piece of code, these will help make it better.

Deprecating Code

As development proceeds, sometimes old ways of doing things have to be replaced by new ways. In many cases, you can just change all the using code in SVN, and move forward. For general interfaces that might be used externally to JMRI, such as in scripts and CATS, it can be good to leave the old interface in place for a while, marking it as "deprecated" so that people can discover that it will eventually go away. After a suitable number of release cycles, the deprecated interface can then be removed.

Note that a deprecated interface is meant to still work. Deprecated should only mean that you can't count on the deprecated interface working in the future, so that it would be good to code away from it while it's still working.

You may want to work with the deprecation checks "on" during compilation. To do that, change this line of build.xml:

<property name="deprecation" value="on" />

This lets you pay attention to new deprecation warnings as you code.

There are two forms of marking something as deprecated (JavaDoc tag and Annotation), and both allow you to add additional information. A nice discussion of the technicalities is here. We use them this way:

* @deprecated 2.7.8

@Deprecated // 2.7.8
where the line contains the version in which the deprecation is applied. That lets you easily know how long ago it was deprecated.