Source code conventions

Classes and interfaces name conventions

Base package for all classes is org.openhubframework.openhub.

There are the following name conventions for classes and interfaces:

...Route	Route implementation
...Converter	Converter implementation
...Service	Service implementation
...DAO	DAO interfaces
...Exception	Exception
...Controller	MVC controller
...Factory	Class that creates another classes
...Test	Test class
...Tools	Class with useful static methods
...Helper	Helper class, usually for local use
...Enum	Enumeration

Method name conventions

There are the following name conventions for methods:

set...	sets value or reference
get...	gets value or reference	Method always returns not-null value or object, never null. It throws exception instead of null.
add...	adds value/reference
update...	data/state change
delete...	data removal
create...	new object creation
exists...	existence check	It returns true or false.
check...	common check	It returns true or false.
validate...	validates input values or internal object state
findAll...	finds all possible values	Never returns null, only empty collection.
findBy... or findXyzBy...	finds value(s) by specified input parameters	If method returns only one value then it can be null.
test...	test method, usually annotated by @Test

Demarcation of transactions - there is expected readonly transaction for methods which have the following prefixes: get, exists, check, findAll, find.

Syntax rules

Adhere to basic Java Code Conventions from Sun/Oracle.

Common syntax rules:

Basic unit of indentation is 4 spaces. Tab should be converted to spaces.
Line length is 120 characters.
Maximum size of one class shouldn't exceed 700 lines.
Use English language exclusively - for class, interface and method names, in comments, GUI, etc.
Use UTF-8 character set in all source code files.

Java imports

Use fully qualified class names in JavaDoc: If not already imported

Class count to use static import with 5.

Names count to use static import with 5.

Import layout:

import static all other imports
<blank line>
import static org.openhubframework.openhub.*
<blank line>
import java.*
import javax.*
<blank line>
import all other imports
<blank line>
import org.openhubframework.openhub.*
<blank line>

How to use TODO?

TODO uses developer for himself, it's not tool for assigning work to anybody else. Never use TODO without username.

Use TODO in the following format where TO_WHOM is developer's username, for example PJUZA, THANUS.

TODO TO_WHOM

JavaDoc

JavaDoc and comments in general are very useful - it's not easy to find balance between many comments without meaningful information and no comments at all. There are few rules which are good to adhere: How to Write Doc Comments for the Javadoc Tool

Use package-info.java file for every package.

@deprecated

We have to adhere backward compatibility and sometimes there is no other possibility then leave old code for deprecation and create new one for next releases.

If any class or method is deprecated then it's necessary to:

use @Deprecated annotation
add @deprecated into JavaDoc with information what to use instead

    /**
     * Helper method which creates input route for asynch. messages.
     *
     * @param route               the route where we want to create asynch. input routing
     * @param routeId             the input route ID
     * @param inUri               the from URI of this route
     *
     * @deprecated Use {@link AsynchRouteBuilder} instead.
     */
    @Deprecated
    public static RouteDefinition createAsynchInRoute(RouteBuilder route, String routeId, String inUri,

Methods or classes marked as deprecated will be removed in next major version.

License header

Use the following Apache license header in all Java classes.

/*
 * Copyright 2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.openhubframework.openhub.spi.alerts;