The SIP Communicator Code Convention

Coding styles have often started religious wars inside projects with different developers trying to prove superiority of the convention they tend to favor. In the SIP Communicator we believe that there is no such thing as a “better” conding style. It is all a matter of habit. However, we do insist on the fact that uniformity is of great importance for assuring code readability. In other words if we want new developers to comply with our coding style it is not because it is the best but simply because the rest of the code is written this way.

Coding Style

The SIP Communicator is a Java application and as such employs the Java Code Convention extending it with the following rules:

  • Opening braces MUST be on their own line (especially those beginning a method).
  • Use 4 spaces to indent everything. Instruct your IDE not to use tabs under any circumstances and replace them with spaces.
  • Use package imports (package.*) and DO NOT import classes themselves.
  • Put your throws clause on its own line (indented) with one exception per line in the case of numerous exception
  • Put your implements and extends clauses on their own lines with a single class/interface per line.

Check this list every now and then as further specifications may be added.

Document Everything

Every method and every class, whether public or internal, MUST start out with a documentation (javadoc) comment that describes what the method (class) does. For methods the documentation must mention every parameter received by the function, return value, and every exception thrown. Use javadoc tags (@param, @returns, @return) when describing each one of these.

Javadoc comments are also highly recommended for most member fields (even when private).

Read over the SIP Communicator code to get an overview of how documentation looks in practice.

IDE Formatting Facilities

For all Eclipse users, we are providing a formatter, that could be imported and used by Eclipse source formatting facilities. Simply download the file, go to the Preferences window of your Eclipse installation, then choose Java/Code style/Formatter and click “Import”.