JSynthLib Programmer's Guide

(based on the official version)

I. Before we start...

First a few words about writing code which will be shared by many developers. This is a project to which many people are joining to. Readability of code is very important.

Even if someone wants to write just a driver for his/her synth, the code will be read by others too. Maybe some changes are necessary since an API change or another developer want take a look how a special issue is solved. Following some rules makes the life easier for all who contribute to JSynthLib.

I.a. Coding Style

During developing driver you will/have to read source codes in JSynthLib distribution. Other programmers will read your source code in the future. Use consistent coding style. Code Conventions for the Java Programming Language is a good reference. Sample codes in The Java Programming Language by Ken Arnold and James Gosling (creators of Java language) are good examples. We encourage you to follow the coding style in these documents especially you are editing source code in core package.

Important note: Please use an indentation level of 4 and a displayed tab width value of 8 (see FAQ for reasons).

I.b. Using Javadoc

Add javadoc on important members (methods and fields). public and protected member must be documented.

I.c. Proper Use of Access Control Modifier (for core developers)

This is especially important for codes under "core/". It would be much easier for programmers to write a driver if the methods and the fields were used properly. If private or protected is used properly, for example, there is no need to grep all files to see how a method or a field is used.

Especially we have to be very careful to make a public (or package) field. If you really need to access it, consider defining a getter or setter method (ex. getFoo() or setFoo()) or using protected.

I.d. Code Sharing

Share the code if possible. Use subclass (inheritance) or static method properly. If you copy a whole method, something wrong. If you divide a long method into several methods, the method would be more easy to be overridden. (More importantly a small method is easy to maintain and would have less bug.)
I.e. Debug/Error Message
Use ErrorMsg.reportStatus("message") for debug message. This way the message is only printed if JSynthLib is run in debugging mode (AKA java -jar JSynthLib.jar 2). Don't use System.out.println.

Use ErrorMsg.reportError("Title", "Message", e) for error message which users need to see.

I.e. Exception Handling

Don't hide Exception just to stop compile error.
 //BAD EXAMPLE
 try {
 ....
 } catch (Exception e) {
 }

This makes debugging difficult. Catch a specific Exception and put a comment, if you know that it is not an error.
 try {
....
} catch (ASpecificException e) {
//This is normal.
}

If it is an error or you are not sure, show a debug message. (Of course, implement proper error handling code if possible.)
 try {
 ....
 } catch (ASpecificException e) {
 ErrorMsg.reportStatus(e);
 }

Again catch a specific Exception. Don't catch Exception without good reason.

next