The Jitsi 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 Jitsi 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

Jitsi 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.
  • We are OK with single-line if-s, while-s, for-s and such not having braces. Using braces in such cases is also fine, of course.
  • When iterating over maps we prefer iterating over the entry sets rather than just going over the keys and then looking up all their respective values.
  • When creating new property to enable/disable a feature, name it so that the default value to be false.

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 Jitsi 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.)