From YaddaWiki

Contents 1 Coding Conventions 1.1 Java coding conventions 1.2 Spacing/indentation 1.3 One line if-s 1.4 Access modifiers 1.5 Interface and implementation naming 1.6 Service name convention 1.7 Module naming conventions 1.8 Loggers and logging 1.9 Automated formatting and import clean up in Eclipse 2 Coding guidelines 2.1 Exception handling 2.1.1 Avoid silently catching the exception 2.1.2 Exceptions and threads 2.2 Iteration 3 Comments 3.1 General rules 3.2 Preamble 3.3 Class comments 3.4 Field/accessor method comments 3.5 Interface comments 4 Tests 4.1 Separation of the unit and integration tests 4.2 Unit test location 4.3 Test method naming

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

1. Do not use "public" and "abstract" modifiers for interface methods.

They are superfluous here.

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

Service name convention

Usually we create a facade to provide API for programmers, and service to maintain remoting. As the service is less used, and sometimes may not be present, it is convenient to:

• name facade interfaces with no suffix (eg. IdManager)
• name service interface with Service suffix (eg. IdManagerService)

Module naming conventions

It is often, that a module comes in two parts: an API and a implementation. In such case use following pattern: - API should have '-api' suffix (like yadda-user-api) - implementation should have no suffix (like yadda-user) It is possible that there is a reason to emphasis that it is an implementation package, and it is possible to add -impl suffix, but it is not a default procedure.

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 (possibly in english):

• what is it
• what is it for
• authors (note: if you do some extensive work on 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.

Tests

Tests are significant part of the programming effort. They not only have to be written, but to be maintained with rest of the code as well. Therefore following rules apply:

Separation of the unit and integration tests

Unit tests are tests, which do not require specific environment to be run, and may be run during each compilation.

Integration tests require specific environment and are not expected to be run during each compilation.

Unit test location

All unit tests are located within standard maven directory structure, in:

src/test/java

All resources required by tests, but not required by the executable code are stored in:

src/test/resources

Unit tests are tests for the classes, so:

• tests referring to the custom class are in the same package as tested class
• tests for the class are in class named ClassNameTest, e.g. for StringConverter tests are StringConverterTest

Test method naming

All testing methods must have clear and significant names. It is recommended, that each test method has name test&ltMethodName>, for method formatString() it would be:

testFormatString()

Or - if there are more than one method with the same name - add a suffix explaining method, starting with a dash (_), e.g.:

testFormatString_2args()
testFormatString_4args()

If for some reason you want to have more than one test for one method add significant soffix explaining test purpouse:

testFormatString_Diacretics()
testFormatString_HtmlEscapes()