From YaddaWiki

Coding Conventions

All ICM development must stick to the following rules about code formatting, conventions etc.

Please, adjust your IDE to match the code formatting patterns described below.

Java coding conventions

We follow the Java code conventions and JSP code conventions with some customization and specific rules which are described below.

Spacing/indentation

1. never use tabs to indent, use 4 spaces instead of one tab
2. if possible break lines longer than 120 chars, try not to excees 160 chars.
3. use 80 chars for javadocs

One line if-s

Excerpt from code conventions:
Braces are used around all statements, even singletons, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.

Access modifiers

Do not use "public" and "abstract" modifiers for interface methods. They are superfluous.

Naming things

Naming parts of code properly is one of the most important things to guarante the code to be readable and clear. The name should clearly indicate what a given part of the code is or does.

Module naming conventions

The name of the module should clearly express the functionality the given module provides, and should be preceded by the name of the application. Let's say the name of the app is football and the module we want to write will be responsible for the persistence layer access(saving, reading, repositories). In such a case the name of the module could be football-persistence.

Package name conventions

We divide the applications by functionalities they provide, not the types of services they are. It doesn't matter if you create a module, a package, a class or a method, the most important thing is that the name should correspond to the functionality the given fragment of the code provides (at least it's first part, e.g. JournalSearchController). It means that instead of package structure like this:

- controller
- service
- dto
...

We would have, for example:

- journal
  - details
  - search
- article
  - details
  - search
- search-common
- security

It's worth noting that it very often doesn't makes sense to create a package unless there are at least a few classes (let's say 3-6) that could make up its content. For example, if we had a journal package and only three classes in it, let's say JournalDetailsController, JournalEditController<code> and <code>JournalEditService we probably wouldn't divide the package into journal.details and journal.edit packages. </code>

Interface and implementation naming

Avoid using IName for the interface name, an interface shall be named without leading I.

Good:

SomeService

Bad:

ISomeService

The following rules apply to implementation naming:

• use a reasonable prefix to declare the point of the implementation, eg.:

JdbcCatalog
CachedCatalog

• if there is really, really only one reasonable implementation of the interface (and you do not expect to ever have another one) you may also use: <Interface name> + Impl, eg.:

SomeServiceImpl

Loggers and logging

SLF4j is since now official logging tool (classes shall use slf4j logging classes and never use other loggers. Details: logging in Yaddda

Automated formatting and import clean up in Eclipse

Eclipse allows to organize imports and format the code before saving of the file.

To enable that you have to select Window->Preferences item from the main menu. Then select Java->Editor->Save Actions option.

Expected settings are:

• enable "Perform the selected actions on save"
• enable "Organize imports"
• in near future enable "Format source code" (but only "Format edited lines", to avoid unnecessary noise in SVN commits).

Coding guidelines

Exception handling

Avoid silently catching the exception

Avoid silently catching the exception - if this is real exception it must be at least logged, preferably on warn level. Exceptions happen, we have a lot of data and if something goes wrong we must know it!

If you drop exception silently it must be documented with proper comment within try block.

Exceptions and threads

Be aware that exceptions raised in manually created threads are silently skipped. Check against any exceptions in the thread code:

 MyThread extends Thread {
     public void run() {
         try {
            //thread execution code
         } catch (Exception e) {
            //exception handling code
         }
     }
 }
 

And whenever starting specific thread it is preferable to use Future, DeskLightTask (in DL) or other class that does proper exception handling.

Iteration

Instead of this:

Iterator<Foo> it = foos.iterator();
while (it.hasNext()) {
    bar(it.next());
}

use this:

for (Foo foo : foos) {
    bar(foo);
}

Comments

Comments are usually helpful for other developers, who need to read and maintain existing code. It is not advised to overcomment, as we prefer to write a readable code, than extensive comments.

General rules

All comments are written in english. It is adviced to use spellchecker feature of IDE to maintain reasonable standards.

Preamble

Each file must have preamble with:

• copyright note (ICM, Warsaw University)
• license note (Usually apache 2.0)

Standard preamble:

TBD.

Class comments

Each class must have a javadoc on itself, describing:

• what it is
• what it is for
• authors (note: if you do some extensive work on a class, put yourself on author list together with previous one).

Field/accessor method comments

If get/set methods are present for a field get is preferred to add javadoc. Idem per idem is not acceptable (i.e. 'setCatalog: this sets the catalog property)

Interface comments

It is obligatory to write extensive javadoc for every interface, no exceptions. This includes:

• interface itself javadoc (what it is, what functionality represents etc.)
• full javadoc of every method (including exceptions, params and return value)
• expected behaviour in border cases (what will happen if passed Collection is null? NullPointerException, or it will be treated as empty list)

Remember, that those comments define contract of the interface, both for users and those who will implement it. If it is clear, then less problems are at the integration time.