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 SIP Communicator we believe that there is no such thing as a “better” coding 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

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.
  • Both code and javadoc are limited at column 80.
  • @param tag values in javadoc do not have any indentation
  • Use <tt> tags (rather than <code>) for monospace (e.g. <tt>true</tt>)
  • When in doubt, ask. There are certainly numerous other rules that are being followed by coders and that have been missed here so try to mimic existing code and feel free to send a question on dev when in doubt.

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”. Note: However please do not use the “auto format” on existing code! (This could add arbitrary line returns in all the code and you could result with a bunch of modifications when just changing a single thing.)