Coding Style

Coding conventions proved to be very important for producing maintainable and reliable code. In db4o production cycle, coding conventions have a special value, as the code ownership is spread over all the members of the team and any developer is able to work with any piece of code.

In general, we follow Code Conventions for the Java Programming Language, however there are some specifics, which can be useful to know for db4o users and core contributors.

This document is supposed to emphasize some of the java coding style recommendations used by db4o and explain db4o specific coding style requirements.

File Header

All code files must have copyright.The normal db4o copyright notice should be created as the standard template in your Eclipse workspace for db4o development.
Window + Preferences + Java + Code Style + Code Templates + Code + New Java Files

/* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com */

${package_declaration}

${typecomment}

${type_declaration}

Naming Conventions

General Naming

All names should be written in English.

English is the preferred language for international development.

Package naming

Package names should be in all lower case.

com.db4o.reflection

Class Naming

Class names should be nouns and written in mixed case starting with upper case.

ObjectContainer, Configuration

Methods Naming

Method names must be verbs and written in mixed case starting with lower case.

isReadOnly(), rename()

Abbreviations and Acronyms

Abbreviations and acronyms should not be uppercase when used as name.

IoAdapter(); // NOT: IOAdapter

Using all uppercase for the base name will give conflicts with the naming conventions given above and will reduce the readability.

Type Naming

Type names must be nouns and written in mixed case starting with upper case.

Db4oList, TransientClass

Variable Naming

Variable names must be in mixed case starting with lower case. Variables should have full sensible name, reflecting their purpose.

listener, objectContainer

Constants

Constants names (final variables) must be all uppercase using underscore to separate words.

ACTIVATION_DEPTH, READ_ONLY

It is a good practice to add methods to retrieve constant values for user interface:

boolean isReadOnly() {

  return _config.getAsBoolean(READ_ONLY);

}

Getters/Setters

Normally we do not use get/set prefix for methods accessing attributes directly, unless such usage adds  valuable information:

public void setStateDirty() {}

In other cases feel free to access attributes by names:

clientServer(), configuration() 

Boolean Methods And Variables

is(can, has, should) prefix should be used for boolean variables and methods.

isDirty(), canHold(reflectClass)

Using the is(can, has, should) prevents choosing bad names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to choose more meaningful names.

Setter methods for boolean variables must have set prefix as in:

public void setStateDirty() {}

Initialize

The term initialize can be used where an object or a concept is established. classIndex.initialize(_targetDb);

Abbreviations like init must be avoided.

Complementary Names

Complementary names must be used for complementary entities:

get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, first/last, up/down, min/max, next/previous, old/new, open/close, show/hide, suspend/resume, etc. For example:

startServer();

stopServer();

This convention helps to distinguish the borders of a logical operation and to recognize opposite action methods.

Abbreviations

Abbreviations in names should be avoided.

copyIdentity (); // NOT: cpIdentity, NOT:copyId

However some well established and commonly used acronyms or abbreviations must be preferred to full names:

html // NOT: HypertextMarkupLanguage
cpu // NOT: CentralProcessingUnit

Named Constants

Named constants should be used instead of:

 - magic numbers:

           if (blockSize > MAX_BLOCK_SIZE) // NOT: blockSize > 256

- fixed phrases:

           if (fieldname == CREATIONTIME_FIELD) // NOT if (fieldname == "i_uuid")

This convention gives a programmer an idea about the meaning of the constant value. At the same time, it makes it easier to change the constant value: the change must be made only in one place. 

Code Organization

Package Structure

Internal class implementations should be placed in com.db4o.internal package. This helps to keep the top-level API smaller and more understandable.

com.db4o.query.Evaluation

has implementation in

com.db4o.internal.query.PredicateEvaluation

Classes and Interfaces

Class and Interface declarations should be organized in the following manner:

  1. Class/Interface documentation.
  2. class or interface statement.
  3. Class (static) variables in the order public, protectedpackage(no access modifier), private.
  4. Instance variables in the order  public, protectedpackage(no access modifier), private.
  5. Constructors.
  6. Methods.

Methods

Group class methods by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make reading and understanding of the code easier.

Wait & Notify

Use Lock4#snooze(), #awake() instead of Object#wait directly for CF reason.


Blank Lines

Use blank lines to separate methods, class variable declarations of different scope, and logical units within a block of code. Consider extracting logical blocks of code into separate methods

Import Declarations

Import declarations should only include package name:.

import java.util.*; // NOT: import java.util.List;

Modern IDEs, such as Eclipse, provide an automated way to create correct import statements (see "Source/Organize Imports" command in Eclipse).

Initialization

Local variables should appear at the beginning of a code block. (A block is any code surrounded by curly braces "{" and "}".) Try to initialize the variable immediately to prevent using uninitialized values.

The exception to the rule is indexes of for loops, which in Java can be declared in the for statement:

for (int i = 0; i < maxLoops; i++) { ... }

Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block:

int count;

...

myMethod() {

    if (condition) {

        int count = 0;     // AVOID!

        ...

    }

    ...

}

Exception Handling

Never use exception#printStackTrace() in db4o productive code.

There are three possible choices that can be used:

Comments

Supply your code with javadoc comments. All public classes and public and protected functions within public classes should be documented. This makes it easy to keep up-to-date online code documentation. If a class or a method is not part of public API use @exlude tag. For further details, see "How to Write Doc Comments for Javadoc"

All comments should be written in English. In an international environment, English is the preferred language.

Avoid using comments to explain tricky code, rather rewrite it to make it self-explanatory.

For more information see: Code Conventions for the Java Programming Language.

This document was compiled based on db4o team coding practices and the following documents:

http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

http://geosoft.no/development/javastyle.html

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html